
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Introduced changes &#8212; Universal Ctags 0.3.0 documentation</title>
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.3.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Request for extenting a parser (or Reporting a bug of parser)" href="reporting.html" />
    <link rel="prev" title="Universal-ctags Hacking Guide" href="index.html" /> 
  </head>
  <body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="reporting.html" title="Request for extenting a parser (or Reporting a bug of parser)"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="index.html" title="Universal-ctags Hacking Guide"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="introduced-changes">
<h1>Introduced changes<a class="headerlink" href="#introduced-changes" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Maintainer:</th><td class="field-body">Masatake YAMATO &lt;<a class="reference external" href="mailto:yamato&#37;&#52;&#48;redhat&#46;com">yamato<span>&#64;</span>redhat<span>&#46;</span>com</a>&gt;</td>
</tr>
</tbody>
</table>
<div class="contents local topic" id="table-of-contents">
<p class="topic-title first"><cite>Table of contents</cite></p>
<ul class="simple">
<li><a class="reference internal" href="#importing-changes-from-exuberant-ctags" id="id2">Importing changes from Exuberant-ctags</a></li>
<li><a class="reference internal" href="#parser-related-changes" id="id3">Parser related changes</a><ul>
<li><a class="reference internal" href="#fully-rewritten-parsers" id="id4">Fully rewritten parsers</a></li>
<li><a class="reference internal" href="#new-parsers" id="id5">New parsers</a></li>
<li><a class="reference internal" href="#heavily-improved-parsers" id="id6">Heavily improved parsers</a></li>
<li><a class="reference internal" href="#f-kind-usage" id="id7"><cite>F</cite> kind usage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-and-extended-options" id="id8">New and extended options</a><ul>
<li><a class="reference internal" href="#wildcard-in-options" id="id9">Wildcard in options</a></li>
<li><a class="reference internal" href="#long-names-in-kinds-fields-and-extra-options" id="id10">Long names in kinds, fields, and extra options</a></li>
<li><a class="reference internal" href="#notice-messages-and-quiet" id="id11">Notice messages and <code class="docutils literal"><span class="pre">--quiet</span></code></a></li>
<li><a class="reference internal" href="#input-encoding-encoding-and-output-encoding-encoding" id="id12"><code class="docutils literal"><span class="pre">--input-encoding=ENCODING</span></code> and <code class="docutils literal"><span class="pre">--output-encoding=ENCODING</span></code></a></li>
<li><a class="reference internal" href="#extra-tag-entries-extras" id="id13">Extra tag entries (<code class="docutils literal"><span class="pre">--extras</span></code>)</a></li>
<li><a class="reference internal" href="#options-for-inspecting-ctags-internals" id="id14">Options for inspecting ctags internals</a></li>
<li><a class="reference internal" href="#kinds-synchronization" id="id15">Kinds synchronization</a></li>
<li><a class="reference internal" href="#put-field-prefix-options" id="id16"><code class="docutils literal"><span class="pre">--put-field-prefix</span></code> options</a></li>
<li><a class="reference internal" href="#maxdepth-option" id="id17"><code class="docutils literal"><span class="pre">--maxdepth</span></code> option</a></li>
<li><a class="reference internal" href="#map-lang-option" id="id18"><code class="docutils literal"><span class="pre">--map-&lt;LANG&gt;</span></code> option</a></li>
<li><a class="reference internal" href="#guessing-parser-from-file-contents-g-option" id="id19">Guessing parser from file contents (<code class="docutils literal"><span class="pre">-G</span></code> option)</a></li>
<li><a class="reference internal" href="#enabling-disabling-pseudo-tags-pseudo-tags-option" id="id20">Enabling/disabling pseudo tags (<code class="docutils literal"><span class="pre">--pseudo-tags</span></code> option)</a></li>
<li><a class="reference internal" href="#json-output" id="id21">JSON output</a></li>
<li><a class="reference internal" href="#always-and-never-as-an-argument-for-tag-relative" id="id22">“always” and “never” as an argument for –tag-relative</a></li>
<li><a class="reference internal" href="#defining-a-macro-in-cpreprocessor-input" id="id23">Defining a macro in CPreProcessor input</a></li>
<li><a class="reference internal" href="#interactive-mode" id="id24"><code class="docutils literal"><span class="pre">--_interactive</span></code> Mode</a></li>
<li><a class="reference internal" href="#defining-a-kind" id="id25">Defining a kind</a></li>
<li><a class="reference internal" href="#defining-an-extra" id="id26">Defining an extra</a></li>
<li><a class="reference internal" href="#defining-a-subparser" id="id27">Defining a subparser</a><ul>
<li><a class="reference internal" href="#basic" id="id28">Basic</a></li>
<li><a class="reference internal" href="#directions" id="id29">Directions</a></li>
<li><a class="reference internal" href="#listing-subparsers" id="id30">Listing subparsers</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#changes-to-the-tags-file-format" id="id31">Changes to the tags file format</a><ul>
<li><a class="reference internal" href="#truncating-the-pattern-for-long-input-lines" id="id32">Truncating the pattern for long input lines</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reference-tags" id="id33">Reference tags</a></li>
<li><a class="reference internal" href="#automatic-parser-selection" id="id34">Automatic parser selection</a><ul>
<li><a class="reference internal" href="#incompatible-changes-to-file-name-pattern-and-extension-handling" id="id35">Incompatible changes to file name pattern and extension handling</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pseudo-tags" id="id36">Pseudo tags</a><ul>
<li><a class="reference internal" href="#tag-kind-description" id="id37"><code class="docutils literal"><span class="pre">TAG_KIND_DESCRIPTION</span></code></a></li>
<li><a class="reference internal" href="#tag-kind-separator" id="id38"><code class="docutils literal"><span class="pre">TAG_KIND_SEPARATOR</span></code></a></li>
<li><a class="reference internal" href="#tag-output-mode" id="id39"><code class="docutils literal"><span class="pre">TAG_OUTPUT_MODE</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#parser-own-fields" id="id40">Parser own fields</a></li>
<li><a class="reference internal" href="#parser-own-extras" id="id41">Parser own extras</a><ul>
<li><a class="reference internal" href="#discussion" id="id42">Discussion</a></li>
</ul>
</li>
<li><a class="reference internal" href="#parser-own-parameter" id="id43">Parser own parameter</a></li>
<li><a class="reference internal" href="#customizing-xref-output" id="id44">Customizing xref output</a></li>
<li><a class="reference internal" href="#incompatible-changes-in-command-line" id="id45">Incompatible changes in command line</a><ul>
<li><a class="reference internal" href="#d-option" id="id46"><code class="docutils literal"><span class="pre">-D</span></code> option</a></li>
</ul>
</li>
<li><a class="reference internal" href="#skipping-utf-8-bom" id="id47">Skipping utf-8 BOM</a></li>
<li><a class="reference internal" href="#readtags" id="id48">Readtags</a><ul>
<li><a class="reference internal" href="#printing-line-numbers-with-n" id="id49">Printing line numbers with <code class="docutils literal"><span class="pre">-n</span></code></a></li>
<li><a class="reference internal" href="#filtering-in-readtags-command" id="id50">Filtering in readtags command</a></li>
<li><a class="reference internal" href="#examples-of-input" id="id51">Examples of input</a></li>
<li><a class="reference internal" href="#examples-of-filter-expressions" id="id52">Examples of filter expressions</a></li>
</ul>
</li>
</ul>
</div>
<hr class="docutils" />
<p>Many changes have been introduced in Universal-ctags. Use git-log to
review changes not enumerated here, especially in language parsers.</p>
<div class="section" id="importing-changes-from-exuberant-ctags">
<h2><a class="toc-backref" href="#id2">Importing changes from Exuberant-ctags</a><a class="headerlink" href="#importing-changes-from-exuberant-ctags" title="Permalink to this headline">¶</a></h2>
<p>See “Exuberant-ctags” in “Tracking other projects” for detailed
information regarding imported changes.</p>
<p>Some changes have also been imported from Fedora and Debian.</p>
</div>
<div class="section" id="parser-related-changes">
<h2><a class="toc-backref" href="#id3">Parser related changes</a><a class="headerlink" href="#parser-related-changes" title="Permalink to this headline">¶</a></h2>
<div class="section" id="fully-rewritten-parsers">
<h3><a class="toc-backref" href="#id4">Fully rewritten parsers</a><a class="headerlink" href="#fully-rewritten-parsers" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>C (see <a class="reference internal" href="parser-cxx.html#cxx"><span class="std std-ref">The new C/C++ parser</span></a>)</li>
<li>C++ (see <a class="reference internal" href="parser-cxx.html#cxx"><span class="std std-ref">The new C/C++ parser</span></a>)</li>
<li>Python (see <a class="reference internal" href="parser-python.html#python"><span class="std std-ref">The new Python parser</span></a>)</li>
<li>HTML (see <a class="reference internal" href="parser-html.html#html"><span class="std std-ref">The new HTML parser</span></a>)</li>
<li>Tcl (see <a class="reference internal" href="parser-tcl.html#tcl"><span class="std std-ref">The new Tcl parser</span></a>)</li>
<li>ITcl (see <a class="reference internal" href="parser-tcl.html#tcl"><span class="std std-ref">The new Tcl parser</span></a>)</li>
</ul>
</div>
<div class="section" id="new-parsers">
<h3><a class="toc-backref" href="#id5">New parsers</a><a class="headerlink" href="#new-parsers" title="Permalink to this headline">¶</a></h3>
<p>The following parsers have been added:</p>
<ul class="simple">
<li>Ada</li>
<li>AnsiblePlaybook <em>libyaml</em></li>
<li>Autoconf</li>
<li>Automake</li>
<li>AutoIt</li>
<li>Clojure</li>
<li>CSS</li>
<li>CUDA</li>
<li>D</li>
<li>DBusIntrospect <em>libxml</em></li>
<li>Diff</li>
<li>DTD</li>
<li>DTS</li>
<li>Elm <em>optlib</em></li>
<li>Falcon</li>
<li>Glade <em>libxml</em></li>
<li>Go</li>
<li>JavaProperties</li>
<li>JSON</li>
<li>GNU linker script(LdScript)</li>
<li>man page <em>optlib</em></li>
<li>Maven2 <em>libxml</em></li>
<li>M4</li>
<li>ObjectiveC</li>
<li>passwd</li>
<li>puppetManifest <em>optlib</em></li>
<li>Perl6</li>
<li>Pod <em>optlib</em></li>
<li>PropertyList(plist) <em>libxml</em></li>
<li>Protobuf</li>
<li>PythonLoggingConfig</li>
<li>QemuHX <em>optlib</em></li>
<li>QtMoc</li>
<li>R</li>
<li>RelaxNG <em>libxml</em></li>
<li>reStructuredText</li>
<li>Robot</li>
<li>RpmSpec</li>
<li>Rust</li>
<li>SystemdUnit</li>
<li>SystemVerilog</li>
<li>SVG <em>libxml</em></li>
<li>TclOO (see <a class="reference internal" href="parser-tcl.html#tcl"><span class="std std-ref">The new Tcl parser</span></a>)</li>
<li>TTCN</li>
<li>WindRes</li>
<li>XSLT v1.0 <em>libxml</em></li>
<li>Yacc</li>
<li>Yaml <em>libyaml</em></li>
<li>YumRepo</li>
<li>Zephir</li>
<li>ctags option library <em>optlib</em></li>
<li>Myrddin</li>
<li>RSpec <em>optlib</em></li>
</ul>
<p>See “Option library” for details on <em>optlib</em>.
Libxml2 is required to use the parser(s) marked with <em>libxml</em>.
Libyaml is required to use the parser(s) marked with <em>libyaml</em>.</p>
<p>TIPS: you can list newly introduced parsers if you also have
Exuberant-ctags installed with following command line:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> diff -ruN &lt;<span class="o">(</span>universal-ctags --list-languages<span class="o">)</span> &lt;<span class="o">(</span>exuberant-ctags --list-languages<span class="o">)</span>  <span class="p">|</span> grep <span class="s1">&#39;^[-+]&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="heavily-improved-parsers">
<h3><a class="toc-backref" href="#id6">Heavily improved parsers</a><a class="headerlink" href="#heavily-improved-parsers" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>Ant (rewritten with <em>libxml</em>)</li>
<li>PHP</li>
<li>Verilog</li>
</ul>
</div>
<div class="section" id="f-kind-usage">
<h3><a class="toc-backref" href="#id7"><cite>F</cite> kind usage</a><a class="headerlink" href="#f-kind-usage" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">F</span></code> is used as a kind letter for file kind in Exuberant-ctags; the
<code class="docutils literal"><span class="pre">F</span></code> was hard-coded in ctags internal. However, we found some built-in
parsers including Ruby uses <code class="docutils literal"><span class="pre">F</span></code> for their own purpose. So if you
find a tag having <code class="docutils literal"><span class="pre">F</span></code> as a kind letter, you cannot say what it is
well: a file name or something peculiar in the language. Long kind
description strings may help you but we are not sure all tools
utilizing <code class="docutils literal"><span class="pre">tags</span></code> file refer the long kind description strings.</p>
<p>Universal-ctags disallows parsers to use <code class="docutils literal"><span class="pre">F</span></code> their own purpose
in both built-in and optlib parsers.</p>
<p><code class="docutils literal"><span class="pre">F</span></code> in built-in parsers are replaced as follows:</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="41%" />
<col width="28%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Language</th>
<th class="head">Long description</th>
<th class="head">Replacement</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>ObjectiveC</td>
<td>field</td>
<td>E</td>
</tr>
<tr class="row-odd"><td>Ruby</td>
<td>singletonMethod</td>
<td>S</td>
</tr>
<tr class="row-even"><td>Rust</td>
<td>method</td>
<td>P</td>
</tr>
<tr class="row-odd"><td>SQL</td>
<td>field</td>
<td>E</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="new-and-extended-options">
<h2><a class="toc-backref" href="#id8">New and extended options</a><a class="headerlink" href="#new-and-extended-options" title="Permalink to this headline">¶</a></h2>
<div class="section" id="wildcard-in-options">
<h3><a class="toc-backref" href="#id9">Wildcard in options</a><a class="headerlink" href="#wildcard-in-options" title="Permalink to this headline">¶</a></h3>
<p>For the purpose of gathering as much as information as possible from
source code the “wildcard”(<code class="docutils literal"><span class="pre">*</span></code>) option value has been introduced.</p>
<p><code class="docutils literal"><span class="pre">--extras=*</span></code></p>
<blockquote>
<div>Enables all extra tags.</div></blockquote>
<p><code class="docutils literal"><span class="pre">--fields=*</span></code></p>
<blockquote>
<div>Enables all available fields.</div></blockquote>
<p><code class="docutils literal"><span class="pre">--&lt;LANG&gt;-kinds=*</span></code></p>
<blockquote>
<div>Enables all available kinds for <code class="docutils literal"><span class="pre">LANG</span></code>.</div></blockquote>
<p><code class="docutils literal"><span class="pre">--kinds-&lt;LANG&gt;=*</span></code></p>
<blockquote>
<div>Alternative representation of <code class="docutils literal"><span class="pre">--&lt;LANG&gt;-kinds=*</span></code>.</div></blockquote>
<p><code class="docutils literal"><span class="pre">--all-kinds=SPEC</span></code></p>
<blockquote>
<div>Applies SPEC as kinds to all available language parsers.</div></blockquote>
<p><code class="docutils literal"><span class="pre">--all-kinds=*</span></code></p>
<blockquote>
<div>Enables all available kinds for all available language parsers.</div></blockquote>
</div>
<div class="section" id="long-names-in-kinds-fields-and-extra-options">
<h3><a class="toc-backref" href="#id10">Long names in kinds, fields, and extra options</a><a class="headerlink" href="#long-names-in-kinds-fields-and-extra-options" title="Permalink to this headline">¶</a></h3>
<p>A letter is used for specifying a kind, a field, or an extra entry.
In Universal-ctags a name can also be used.</p>
<p>Surround the name with braces (<cite>{</cite> and <cite>}</cite>) in values assigned to the
options, <code class="docutils literal"><span class="pre">--kind-&lt;LANG&gt;=</span></code>, <code class="docutils literal"><span class="pre">--fields=</span></code>, or <code class="docutils literal"><span class="pre">--extras=</span></code>.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --kinds-C<span class="o">=</span>+L-d ...
</pre></div>
</div>
<p>This command line uses the letters, <cite>L</cite> for enabling the label kind
and <cite>d</cite> for disabling the macro kind of C. The command line can be
rewritten with the associated names.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --kinds-C<span class="o">=</span><span class="s1">&#39;+{label}-{macro}&#39;</span> ...
</pre></div>
</div>
<p>The quotes are needed because braces are interpreted as meta
characters by the shell.</p>
<p>The available names can be listed with <code class="docutils literal"><span class="pre">--list-kinds-full</span></code>,
<code class="docutils literal"><span class="pre">--list-fields</span></code>, or <code class="docutils literal"><span class="pre">--list-extras</span></code>.</p>
</div>
<div class="section" id="notice-messages-and-quiet">
<h3><a class="toc-backref" href="#id11">Notice messages and <code class="docutils literal"><span class="pre">--quiet</span></code></a><a class="headerlink" href="#notice-messages-and-quiet" title="Permalink to this headline">¶</a></h3>
<p>There were 3 classes of message in ctags:</p>
<p><em>fatal</em></p>
<blockquote>
<div>A critical error has occurred and ctags aborts the execution.</div></blockquote>
<p><em>warning</em></p>
<blockquote>
<div>An error has occurred but ctags continues the execution.</div></blockquote>
<p><em>verbose</em></p>
<blockquote>
<div>Mainly used for debugging purposes.</div></blockquote>
<p><em>notice</em> is a new class of message. It is less important than
<em>warning</em> but more important for users than <em>verbose</em>.</p>
<p>Generally the user can ignore <em>notice</em> class messages and <code class="docutils literal"><span class="pre">--quiet</span></code>
can be used to disable them.</p>
</div>
<div class="section" id="input-encoding-encoding-and-output-encoding-encoding">
<h3><a class="toc-backref" href="#id12"><code class="docutils literal"><span class="pre">--input-encoding=ENCODING</span></code> and <code class="docutils literal"><span class="pre">--output-encoding=ENCODING</span></code></a><a class="headerlink" href="#input-encoding-encoding-and-output-encoding-encoding" title="Permalink to this headline">¶</a></h3>
<p>Japanese programmers sometimes use the Japanese language in source
code comments. Of course, it is not limited to Japanese. People may
use their own native language and in such cases encoding becomes an
issue.</p>
<p>ctags doesn’t consider the input encoding; it just reads input as a
sequence of bytes and uses them as is when writing tags entries.</p>
<p>On the other hand Vim does consider input encoding. When loading a
file, Vim converts the file contents into an internal format with one
of the encodings specified in its <cite>fileencodings</cite> option.</p>
<p>As a result of this difference, Vim cannot always move the cursor to
the definition of a tag as users expect when attempting to match the
patterns in a tags file.</p>
<p>The good news is that there is a way to notify Vim of the encoding
used in a tags file with the <code class="docutils literal"><span class="pre">TAG_FILE_ENCODING</span></code> pseudo tag.</p>
<p>Two new options have been introduced (<code class="docutils literal"><span class="pre">--input-encoding=IN</span></code> and
<code class="docutils literal"><span class="pre">--output-encoding=OUT</span></code>).</p>
<p>Using the encoding specified with these options ctags converts input
from <code class="docutils literal"><span class="pre">IN</span></code> to <code class="docutils literal"><span class="pre">OUT</span></code>. ctags uses the converted strings when writing
the pattern parts of each tag line. As a result the tags output is
encoded in <code class="docutils literal"><span class="pre">OUT</span></code> encoding.</p>
<p>In addition <code class="docutils literal"><span class="pre">OUT</span></code> is specified at the top the tags file as the
value for the <code class="docutils literal"><span class="pre">TAG_FILE_ENCODING</span></code> pseudo tag. The default value of
<code class="docutils literal"><span class="pre">OUT</span></code> is UTF-8.</p>
<p>NOTE: Converted input is NOT passed to language parsers.
The parsers still deal with input as a byte sequence.</p>
<p>With <code class="docutils literal"><span class="pre">--input-encoding-&lt;LANG&gt;=IN</span></code>, you can specify a specific input
encoding for <code class="docutils literal"><span class="pre">LANG</span></code>. It overrides the global default value given
with <code class="docutils literal"><span class="pre">--input-encoding</span></code>.</p>
<p>The example usage can be found in <em>Tmain/{input,output}-encoding-option.d</em>.</p>
<p>Acceptable <code class="docutils literal"><span class="pre">IN</span></code> and <code class="docutils literal"><span class="pre">OUT</span></code> values can be listed with <em>iconv -l</em> or
<em>iconv –list</em>. It is platform dependant.</p>
<p>To enable the option, libiconv is needed on your platform. In addition
<code class="docutils literal"><span class="pre">--enable-iconv</span></code> must be given to configure before making ctags.
On Windows mingw32, you must specify <code class="docutils literal"><span class="pre">WITH_ICONV=yes</span></code> like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">C</span><span class="p">:</span>\<span class="n">dev</span>\<span class="n">ctags</span><span class="o">&gt;</span><span class="n">mingw32</span><span class="o">-</span><span class="n">make</span> <span class="o">-</span><span class="n">f</span> <span class="n">mk_mingw</span><span class="o">.</span><span class="n">mak</span> <span class="n">WITH_ICONV</span><span class="o">=</span><span class="n">yes</span>
</pre></div>
</div>
</div>
<div class="section" id="extra-tag-entries-extras">
<h3><a class="toc-backref" href="#id13">Extra tag entries (<code class="docutils literal"><span class="pre">--extras</span></code>)</a><a class="headerlink" href="#extra-tag-entries-extras" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">--extra</span></code> option in Exuberant-ctags is renamed to <code class="docutils literal"><span class="pre">--extras</span></code> (plural) in
Universal-ctags for making consistent with <code class="docutils literal"><span class="pre">--kinds-&lt;LANG&gt;</span></code> and <code class="docutils literal"><span class="pre">--fields</span></code>.</p>
<p>These extra tag entries are newly introduced.</p>
<p><code class="docutils literal"><span class="pre">F</span></code></p>
<blockquote>
<div>Equivalent to –file-scope.</div></blockquote>
<p><code class="docutils literal"><span class="pre">p</span></code></p>
<blockquote>
<div>Include pseudo tags.</div></blockquote>
</div>
<div class="section" id="options-for-inspecting-ctags-internals">
<h3><a class="toc-backref" href="#id14">Options for inspecting ctags internals</a><a class="headerlink" href="#options-for-inspecting-ctags-internals" title="Permalink to this headline">¶</a></h3>
<p>Exuberant-ctags provides a way to inspect its internals via
<code class="docutils literal"><span class="pre">--list-kinds</span></code>, <code class="docutils literal"><span class="pre">--list-languages</span></code>, and <code class="docutils literal"><span class="pre">--list-maps</span></code>.</p>
<p>This idea has been expanded in Universal-ctags with
<code class="docutils literal"><span class="pre">--list-kinds-full</span></code>, <code class="docutils literal"><span class="pre">--list-map-extensions</span></code>,  <code class="docutils literal"><span class="pre">--list-extras</span></code>,
<code class="docutils literal"><span class="pre">--list-features</span></code>, <code class="docutils literal"><span class="pre">--list-fields</span></code>, <code class="docutils literal"><span class="pre">--list-map-patterns</span></code>, and
<code class="docutils literal"><span class="pre">--list-pseudo-tags</span></code> being added.</p>
<p>The original three <code class="docutils literal"><span class="pre">--list-</span></code> options are not changed for
compatibility reasons, however, the newly introduced options are
recommended for all future use.</p>
<p>By default, interactive use is assumed and ctags tries aligning the
list output in columns for easier reading.</p>
<p>When <code class="docutils literal"><span class="pre">--machinable</span></code> is given before a <code class="docutils literal"><span class="pre">--list-</span></code> option, ctags
outputs the list in a format more suitable for processing by scripts.
Tab characters are used as separators between columns. The alignment
of columns is never considered when <code class="docutils literal"><span class="pre">--machinable</span></code> is given.</p>
<p>Currently only <code class="docutils literal"><span class="pre">--list-extras</span></code>, <code class="docutils literal"><span class="pre">--list-fields</span></code> and
<code class="docutils literal"><span class="pre">--list-kinds-full</span></code> support <code class="docutils literal"><span class="pre">--machinable</span></code> output.</p>
<p>These new <code class="docutils literal"><span class="pre">--list-</span></code> options also print a column header, a line
representing the name of each column. The header may help users and
scripts to understand and recognize the columns. Ignoring the column
header is easy because it starts with a <cite>#</cite> character.</p>
<p><code class="docutils literal"><span class="pre">--with-list-header=no</span></code> suppresses output of the column header.</p>
</div>
<div class="section" id="kinds-synchronization">
<h3><a class="toc-backref" href="#id15">Kinds synchronization</a><a class="headerlink" href="#kinds-synchronization" title="Permalink to this headline">¶</a></h3>
<p>In Universal-ctags, as in Exuberant-ctags, most kinds are parser
local; enabling (or disabling) a kind in a parser has no effect on
kinds in any other parsers even those with the same name and/or
letter.</p>
<p>However, there are exceptions, such as C and C++ for example. C++ can
be considered a language extended from C. Therefore it is natural
that all kinds defined in the C parser are also defined in the C++
parser. Enabling a kind in the C parser also enables a kind having
the same name in the C++ parser, and vice versa.</p>
<p>A kind group is a group of kinds satisfying the following conditions:</p>
<ol class="arabic simple">
<li>Having the same name and letter, and</li>
<li>Being synchronized with each other</li>
</ol>
<p>A master parser manages the synchronization of a kind group. The
<cite>MASTER</cite> column of <code class="docutils literal"><span class="pre">--list-kinds-full</span></code> shows the master parser of
the kind.</p>
<p>Internally, a state change (enabled or disabled with
<code class="docutils literal"><span class="pre">--kind-&lt;LANG&gt;=[+|-]...</span></code>) of a kind in a kind group is reported to
its master parser as an event. Then the master parser updates the
state of all kinds in the kind group as specified with the option.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-kinds-full<span class="o">=</span>C++
<span class="gp">#</span>LETTER NAME            ENABLED  REFONLY NROLES MASTER     DESCRIPTION
<span class="go">d       macro           on       FALSE   1      C          macro definitions</span>
<span class="go">...</span>
<span class="gp">$</span> ./ctags --list-kinds-full<span class="o">=</span>C
<span class="gp">#</span>LETTER NAME            ENABLED  REFONLY NROLES MASTER     DESCRIPTION
<span class="go">d       macro           on       FALSE   1      C          macro definitions</span>
<span class="go">...</span>
</pre></div>
</div>
<p>The example output indicates that the <cite>d</cite> kinds of both the C++ and C
parsers are in the same group and that the <cite>C</cite> parser manages the
group.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --kinds-C++<span class="o">=</span>-d --list-kinds-full<span class="o">=</span>C <span class="p">|</span> head -2
<span class="gp">#</span>LETTER NAME            ENABLED  REFONLY NROLES MASTER     DESCRIPTION
<span class="go">d       macro           off      FALSE   1      C          macro definitions</span>
<span class="gp">$</span> ./ctags --kinds-C<span class="o">=</span>-d --list-kinds-full<span class="o">=</span>C <span class="p">|</span> head -2
<span class="gp">#</span>LETTER NAME            ENABLED  REFONLY NROLES MASTER     DESCRIPTION
<span class="go">d       macro           off      FALSE   1      C          macro definitions</span>
<span class="gp">$</span> ./ctags --kinds-C++<span class="o">=</span>-d --list-kinds-full<span class="o">=</span>C++ <span class="p">|</span> head -2
<span class="gp">#</span>LETTER NAME            ENABLED  REFONLY NROLES MASTER     DESCRIPTION
<span class="go">d       macro           off      FALSE   1      C          macro definitions</span>
<span class="gp">$</span> ./ctags --kinds-C<span class="o">=</span>-d --list-kinds-full<span class="o">=</span>C++ <span class="p">|</span> head -2
<span class="gp">#</span>LETTER NAME            ENABLED  REFONLY NROLES MASTER     DESCRIPTION
<span class="go">d       macro           off      FALSE   1      C          macro definitions</span>
</pre></div>
</div>
<p>In the above example, the <cite>d</cite> kind is disabled via C or C++.
Disabling a <cite>d</cite> kind via one language disables the <cite>d</cite> kind for the
other parser, too.</p>
</div>
<div class="section" id="put-field-prefix-options">
<h3><a class="toc-backref" href="#id16"><code class="docutils literal"><span class="pre">--put-field-prefix</span></code> options</a><a class="headerlink" href="#put-field-prefix-options" title="Permalink to this headline">¶</a></h3>
<p>Some fields are newly introduced in Universal-ctags and more will be
introduced in the future. Other tags generators may also introduce
their own fields.</p>
<p>In such a situation there is a concern about conflicting field names;
mixing tags files generated by multiple tags generators including
Universal-ctags is difficult.</p>
<p><code class="docutils literal"><span class="pre">--put-field-prefix</span></code> provides a workaround for this use case. When
<code class="docutils literal"><span class="pre">--put-field-prefix</span></code> is given, ctags adds “UCTAGS” as a prefix to
newly introduced fields.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cat /tmp/foo.h
<span class="gp">#</span>include &lt;stdio.h&gt;
<span class="gp">$</span> ./ctags -o - --extras<span class="o">=</span>+r --fields<span class="o">=</span>+r /tmp/foo.h
<span class="go">stdio.h     /tmp/foo.h      /^#include &lt;stdio.h&gt;/;&quot; h       role:system</span>
<span class="gp">$</span> ./ctags --put-field-prefix -o - --extras<span class="o">=</span>+r --fields<span class="o">=</span>+r /tmp/foo.h
<span class="go">stdio.h     /tmp/foo.h      /^#include &lt;stdio.h&gt;/;&quot; h       UCTAGSrole:system</span>
</pre></div>
</div>
<p>In this example, <code class="docutils literal"><span class="pre">role</span></code> is prefixed.</p>
</div>
<div class="section" id="maxdepth-option">
<h3><a class="toc-backref" href="#id17"><code class="docutils literal"><span class="pre">--maxdepth</span></code> option</a><a class="headerlink" href="#maxdepth-option" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">--maxdepth</span></code> limits the depth of directory recursion enabled with
the <code class="docutils literal"><span class="pre">-R</span></code> option.</p>
</div>
<div class="section" id="map-lang-option">
<h3><a class="toc-backref" href="#id18"><code class="docutils literal"><span class="pre">--map-&lt;LANG&gt;</span></code> option</a><a class="headerlink" href="#map-lang-option" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">--map-&lt;LANG&gt;</span></code> is newly introduced to control the file name
to language mappings (langmap) with finer granularity than
<code class="docutils literal"><span class="pre">--langmap</span></code> allows.</p>
<p>A langmap entry is defined as a pair; the name of the language and a
file name extension (or pattern).</p>
<p>Here we use “spec” as a generic term representing both file name
extensions and patterns.</p>
<p><code class="docutils literal"><span class="pre">--langmap</span></code> maps specs to languages exclusively:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ ./ctags --langdef=FOO --langmap=FOO:+.ABC \
          --langdef=BAR --langmap=BAR:+.ABC  \
          --list-maps | grep &#39;\*.ABC$&#39;
BAR      *.ABC
</pre></div>
</div>
<p>Though language <cite>FOO</cite> is added before <cite>BAR</cite>, only <cite>BAR</cite> is set as a
handler for the spec <cite>*.ABC</cite>.</p>
<p>Universal-ctags enables multiple parsers to be configured for a spec.
The appropriate parser for a given input file can then be chosen by a
variety of internal guessing strategies (see “Choosing a proper
parser in ctags”).</p>
<p>Let’s see how specs can be mapped non-exclusively with
<code class="docutils literal"><span class="pre">--map-&lt;LANG&gt;</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="o">./</span><span class="n">ctags</span> <span class="o">--</span><span class="n">langdef</span><span class="o">=</span><span class="n">FOO</span> <span class="o">--</span><span class="nb">map</span><span class="o">-</span><span class="n">FOO</span><span class="o">=+.</span><span class="n">ABC</span> \
          <span class="o">--</span><span class="n">langdef</span><span class="o">=</span><span class="n">BAR</span> <span class="o">--</span><span class="nb">map</span><span class="o">-</span><span class="n">BAR</span><span class="o">=+.</span><span class="n">ABC</span> \
          <span class="o">--</span><span class="nb">list</span><span class="o">-</span><span class="n">maps</span> <span class="o">|</span> <span class="n">grep</span> <span class="s1">&#39;\*.ABC$&#39;</span>
<span class="n">FOO</span>      <span class="o">*.</span><span class="n">ABC</span>
<span class="n">BAR</span>      <span class="o">*.</span><span class="n">ABC</span>
</pre></div>
</div>
<p>Both <cite>FOO</cite> and <cite>BAR</cite> are registered as handlers for the spec <cite>*.ABC</cite>.</p>
<p><code class="docutils literal"><span class="pre">--map-&lt;LANG&gt;</span></code> can also be used for removing a langmap entry.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>$ ./ctags --langdef=FOO --map-FOO=+.ABC \
          --langdef=BAR --map-BAR=+.ABC \
          --map-FOO=-.ABC --list-maps | grep &#39;\*.ABC$&#39;
BAR      *.ABC

$ ./ctags --langdef=FOO --map-FOO=+.ABC \
          --langdef=BAR --map-BAR=+.ABC \
          --map-BAR=-.ABC --list-maps | grep &#39;\*.ABC$&#39;
FOO      *.ABC

$./ctags --langdef=FOO --map-FOO=+.ABC \
         --langdef=BAR --map-BAR=+.ABC \
         --map-BAR=-.ABC --map-FOO=-.ABC  --list-maps | grep &#39;\*.ABC$&#39;
(NOTHING)
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">--langmap</span></code> provides a way to manipulate the langmap in a
spec-centric manner and <code class="docutils literal"><span class="pre">--map-&lt;LANG&gt;</span></code> provides a way to manipulate
the langmap in a parser-centric manner.</p>
</div>
<div class="section" id="guessing-parser-from-file-contents-g-option">
<h3><a class="toc-backref" href="#id19">Guessing parser from file contents (<code class="docutils literal"><span class="pre">-G</span></code> option)</a><a class="headerlink" href="#guessing-parser-from-file-contents-g-option" title="Permalink to this headline">¶</a></h3>
<p>See “Choosing a proper parser in ctags” section.</p>
</div>
<div class="section" id="enabling-disabling-pseudo-tags-pseudo-tags-option">
<h3><a class="toc-backref" href="#id20">Enabling/disabling pseudo tags (<code class="docutils literal"><span class="pre">--pseudo-tags</span></code> option)</a><a class="headerlink" href="#enabling-disabling-pseudo-tags-pseudo-tags-option" title="Permalink to this headline">¶</a></h3>
<p>Each pseudo tag can be enabled/disabled with <code class="docutils literal"><span class="pre">--pseudo-tags</span></code>.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">pseudo</span><span class="o">-</span><span class="n">tags</span><span class="o">=+</span><span class="n">ptag</span>
<span class="o">--</span><span class="n">pseudo</span><span class="o">-</span><span class="n">tags</span><span class="o">=-</span><span class="n">ptag</span>
</pre></div>
</div>
<p>When prefixed with <cite>+</cite>, the pseudo tag specified as <code class="docutils literal"><span class="pre">ptag</span></code> is
enabled.  When prefixed with <cite>-</cite>, the pseudo tag is disabled.
<code class="docutils literal"><span class="pre">--list-pseudo-tags</span></code> shows all recognized ptag names.</p>
<p>All pseudo tags are enabled if <cite>*</cite> is given as the value of ptag
like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">pseudo</span><span class="o">-</span><span class="n">tags</span><span class="o">=</span><span class="s1">&#39;*&#39;</span>
</pre></div>
</div>
<p>All pseudo tags are disabled if no option value is given to
<code class="docutils literal"><span class="pre">--pseudo-tags</span></code> like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">pseudo</span><span class="o">-</span><span class="n">tags</span><span class="o">=</span>
</pre></div>
</div>
<p>To specify only a single pseudo tag, omit the sign:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">pseudo</span><span class="o">-</span><span class="n">tags</span><span class="o">=</span><span class="n">ptag</span>
</pre></div>
</div>
</div>
<div class="section" id="json-output">
<h3><a class="toc-backref" href="#id21">JSON output</a><a class="headerlink" href="#json-output" title="Permalink to this headline">¶</a></h3>
<p>Experimental JSON output has been added. <code class="docutils literal"><span class="pre">--output-format</span></code> can be
used to enable it.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --output-format<span class="o">=</span>json --fields<span class="o">=</span>-s /tmp/foo.py
<span class="go">{&quot;_type&quot;: &quot;tag&quot;, &quot;name&quot;: &quot;Foo&quot;, &quot;path&quot;: &quot;/tmp/foo.py&quot;, &quot;pattern&quot;: &quot;/^class Foo:$/&quot;, &quot;kind&quot;: &quot;class&quot;}</span>
<span class="go">{&quot;_type&quot;: &quot;tag&quot;, &quot;name&quot;: &quot;doIt&quot;, &quot;path&quot;: &quot;/tmp/foo.py&quot;, &quot;pattern&quot;: &quot;/^    def doIt():$/&quot;, &quot;kind&quot;: &quot;member&quot;}</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="output-json.html#output-json"><span class="std std-ref">JSON output</span></a> for more details.</p>
</div>
<div class="section" id="always-and-never-as-an-argument-for-tag-relative">
<h3><a class="toc-backref" href="#id22">“always” and “never” as an argument for –tag-relative</a><a class="headerlink" href="#always-and-never-as-an-argument-for-tag-relative" title="Permalink to this headline">¶</a></h3>
<p>Even if “yes” is specified as an option argument for –tag-relative,
absolute paths are used in tags output if an input is given as
an absolute path. This behavior is expected in exuberant-ctags
as written in its man-page.</p>
<p>In addition to “yes” and “no”, universal-ctags takes “never” and “always”.</p>
<p>If “never” is given, absolute paths are used in tags output regardless
of the path representation for input file(s). If “always” is given,
relative paths are used always.</p>
</div>
<div class="section" id="defining-a-macro-in-cpreprocessor-input">
<h3><a class="toc-backref" href="#id23">Defining a macro in CPreProcessor input</a><a class="headerlink" href="#defining-a-macro-in-cpreprocessor-input" title="Permalink to this headline">¶</a></h3>
<p>Newly introduced <code class="docutils literal"><span class="pre">-D</span></code> option extends the function provided by
<code class="docutils literal"><span class="pre">-I</span></code> option.</p>
<p><code class="docutils literal"><span class="pre">-D</span></code> emulates the behaviour of the corresponding gcc option:
it defines a C preprocessor macro. All types of macros are supported,
including the ones with parameters and variable arguments.
Stringification, token pasting and recursive macro expansion are also supported.</p>
<p><code class="docutils literal"><span class="pre">-I</span></code> is now simply a backward-compatible syntax to define a
macro with no replacement.</p>
<p>Some examples follow.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ctags ... -D IGNORE_THIS ...
</pre></div>
</div>
<p>With this commandline the following C/C++ input</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">IGNORE_THIS</span> <span class="n">a</span><span class="p">;</span>
</pre></div>
</div>
<p>will be processed as if it was</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">a</span><span class="p">;</span>
</pre></div>
</div>
<p>Defining a macro with parameters uses the following syntax:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ctags ... -D <span class="s2">&quot;foreach(arg)=for(arg;;)&quot;</span> ...
</pre></div>
</div>
<p>This example defines <cite>for(arg;;)</cite> as the replacement <cite>foreach(arg)</cite>.
So the following C/C++ input</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="n">foreach</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span> <span class="n">p</span><span class="p">,</span><span class="n">pointers</span><span class="p">)</span>
<span class="p">{</span>

<span class="p">}</span>
</pre></div>
</div>
<p>is processed in new C/C++ parser as:</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="k">for</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span> <span class="n">p</span><span class="p">;;)</span>
<span class="p">{</span>

<span class="p">}</span>
</pre></div>
</div>
<p>and the p local variable can be extracted.</p>
<p>The previous commandline includes quotes since the macros generally contain
characters that are treated specially by the shells. You may need some escaping.</p>
<p>Token pasting is performed by the ## operator, just like in the normal
C preprocessor.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ctags ... -D <span class="s2">&quot;DECLARE_FUNCTION(prefix)=int prefix ## Call();&quot;</span>
</pre></div>
</div>
<p>So the following code</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="n">DECLARE_FUNCTION</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="n">DECLARE_FUNCTION</span><span class="p">(</span><span class="n">b</span><span class="p">)</span>
</pre></div>
</div>
<p>will be processed as</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">aCall</span><span class="p">();</span>
<span class="kt">int</span> <span class="nf">bCall</span><span class="p">();</span>
</pre></div>
</div>
<p>Macros with variable arguments use the gcc __VA_ARGS__ syntax.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ctags ... -D <span class="s2">&quot;DECLARE_FUNCTION(name,...)=int name(__VA_ARGS__);&quot;</span>
</pre></div>
</div>
<p>So the following code</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="n">DECLARE_FUNCTION</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span><span class="kt">int</span> <span class="n">b</span><span class="p">)</span>
</pre></div>
</div>
<p>will be processed as</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">x</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span><span class="kt">int</span> <span class="n">b</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="interactive-mode">
<h3><a class="toc-backref" href="#id24"><code class="docutils literal"><span class="pre">--_interactive</span></code> Mode</a><a class="headerlink" href="#interactive-mode" title="Permalink to this headline">¶</a></h3>
<p>A new <code class="docutils literal"><span class="pre">--_interactive</span></code> option launches a JSON based command REPL which
can be used to control ctags generation programmatically.</p>
<p>See <a class="reference internal" href="interactive-mode.html#interactive-mode"><span class="std std-ref">–_interactive Mode</span></a> for more details.</p>
<p><code class="docutils literal"><span class="pre">--_interactive=sandbox</span></code> adds up seccomp filter. See
<a class="reference internal" href="interactive-mode.html#sandbox-submode"><span class="std std-ref">sandbox submode</span></a> for more details.</p>
</div>
<div class="section" id="defining-a-kind">
<h3><a class="toc-backref" href="#id25">Defining a kind</a><a class="headerlink" href="#defining-a-kind" title="Permalink to this headline">¶</a></h3>
<p>A new <code class="docutils literal"><span class="pre">--kinddef-&lt;LANG&gt;=letter,name,description</span></code> option reduces the
typing defining a regex pattern with <code class="docutils literal"><span class="pre">--regex-&lt;LANG&gt;=</span></code>, and keeps
the consistency of dynamically defined kinds in a language.</p>
<p>A kind letter defined with <code class="docutils literal"><span class="pre">--kinddef-&lt;LANG&gt;</span></code> can be referred in
<code class="docutils literal"><span class="pre">--kinddef-&lt;LANG&gt;</span></code>.</p>
<p>Previously you had to write in your optlib:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>--regex-elm=/^([[:lower:]_][[:alnum:]_]*)[^=]*=$/\1/f,function,Functions/{scope=set}
--regex-elm=/^[[:blank:]]+([[:lower:]_][[:alnum:]_]*)[^=]*=$/\1/f,function,Functions/{scope=ref}
</pre></div>
</div>
<p>With new <code class="docutils literal"><span class="pre">--kinddef-&lt;LANG&gt;</span></code> you can write the same things like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>--kinddef-elm=f,function,Functions
--regex-elm=/^([[:lower:]_][[:alnum:]_]*)[^=]*=$/\1/f/{scope=set}
--regex-elm=/^[[:blank:]]+([[:lower:]_][[:alnum:]_]*)[^=]*=$/\1/f/{scope=ref}
</pre></div>
</div>
<p>We can say now “kind” is a first class object in Universal-ctags.</p>
</div>
<div class="section" id="defining-an-extra">
<h3><a class="toc-backref" href="#id26">Defining an extra</a><a class="headerlink" href="#defining-an-extra" title="Permalink to this headline">¶</a></h3>
<p>A new <code class="docutils literal"><span class="pre">--extradef-&lt;LANG&gt;=name,description</span></code> option allows you to
defining a parser own extra which turning on and off can be
referred from a regex based parser for <code class="docutils literal"><span class="pre">&lt;LANG&gt;</span></code>.</p>
<p>See <a class="reference internal" href="optlib.html#extras"><span class="std std-ref">Conditional tagging with extras</span></a> for more details.</p>
</div>
<div class="section" id="defining-a-subparser">
<span id="defining-subparsers"></span><h3><a class="toc-backref" href="#id27">Defining a subparser</a><a class="headerlink" href="#defining-a-subparser" title="Permalink to this headline">¶</a></h3>
<div class="section" id="basic">
<h4><a class="toc-backref" href="#id28">Basic</a><a class="headerlink" href="#basic" title="Permalink to this headline">¶</a></h4>
<p>About the concept of subparser, see <a class="reference internal" href="running-multi-parsers.html#base-sub-parsers"><span class="std std-ref">Tagging definitions of higher(upper) level language (sub/base)</span></a>.</p>
<p>With <code class="docutils literal"><span class="pre">base</span></code> long flag of <cite>–langdef=&lt;LANG&gt;</cite> option, you can define
a subparser for a specified base parser. Combining with <code class="docutils literal"><span class="pre">--kinddef-&lt;LANG&gt;</span></code>
and <code class="docutils literal"><span class="pre">--regex-&lt;KIND&gt;</span></code> options, you can extend an existing parser
without risk of kind confliction.</p>
<p>Let’s see an example.</p>
<p>input.c</p>
<div class="highlight-C"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span> <span class="nf">set_one_prio</span><span class="p">(</span><span class="k">struct</span> <span class="n">task_struct</span> <span class="o">*</span><span class="n">p</span><span class="p">,</span> <span class="kt">int</span> <span class="n">niceval</span><span class="p">,</span> <span class="kt">int</span> <span class="n">error</span><span class="p">)</span>
<span class="p">{</span>
<span class="p">}</span>

<span class="n">SYSCALL_DEFINE3</span><span class="p">(</span><span class="n">setpriority</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">which</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">who</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">niceval</span><span class="p">)</span>
<span class="p">{</span>
        <span class="p">...;</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span>./ctags --options<span class="o">=</span>NONE  -x --_xformat<span class="o">=</span><span class="s2">&quot;%20N %10K %10l&quot;</span>  -o - input.c
<span class="go">ctags: Notice: No options will be read from files or environment</span>
<span class="go">        set_one_prio   function          C</span>
<span class="go">     SYSCALL_DEFINE3   function          C</span>
</pre></div>
</div>
<p>C parser doesn’t understand that <cite>SYSCALL_DEFINE3</cite> is a macro for defining an
entry point for a system.</p>
<p>Let’s define <cite>linux</cite> subparser which using C parser as a base parser:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cat linux.ctags
<span class="go">--langdef=linux{base=C}</span>
<span class="go">--kinddef-linux=s,syscall,system calls</span>
<span class="go">--regex-linux=/SYSCALL_DEFINE[0-9]\(([^, )]+)[\),]*/\1/s/</span>
</pre></div>
</div>
<p>The output is change as follows with <cite>linux</cite> parser:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --options<span class="o">=</span>NONE --options<span class="o">=</span>./linux.ctags -x --_xformat<span class="o">=</span><span class="s2">&quot;%20N %10K %10l&quot;</span>  -o - input.c
<span class="go">ctags: Notice: No options will be read from files or environment</span>
<span class="go">         setpriority    syscall      linux</span>
<span class="go">        set_one_prio   function          C</span>
<span class="go">     SYSCALL_DEFINE3   function          C</span>
</pre></div>
</div>
<p><cite>setpriority</cite> is recognized as a <cite>syscall</cite> of <cite>linux</cite>.</p>
<p>Using only <cite>–regex-C=…</cite> you can capture <cite>setpriority</cite>.
However, there were concerns about kind confliction; when introducing
a new kind with <cite>–regex-C=…</cite>, you cannot use a letter and name already
used in C parser and <cite>–regex-C=…</cite> options specified in the other places.</p>
<p>You can use a newly defined subparser as a new namespace of kinds.
In addition you can enable/disable with the subparser usable
<cite>–languages=[+|-]</cite> option:</p>
</div>
<div class="section" id="directions">
<h4><a class="toc-backref" href="#id29">Directions</a><a class="headerlink" href="#directions" title="Permalink to this headline">¶</a></h4>
<p>As explained in <a class="reference internal" href="running-multi-parsers.html#base-sub-parsers"><span class="std std-ref">Tagging definitions of higher(upper) level language (sub/base)</span></a>,
you can choose direction(s) how a base parser and a guest parser work together with
long flags putting after <cite>–langdef=Foo{base=Bar}</cite>.</p>
<table border="1" class="docutils">
<colgroup>
<col width="52%" />
<col width="48%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">C level notation</th>
<th class="head">Command line long flag</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>SUBPARSER_BASE_RUNS_SUB</td>
<td>shared</td>
</tr>
<tr class="row-odd"><td>SUBPARSER_SUB_RUNS_BASE</td>
<td>dedicated</td>
</tr>
<tr class="row-even"><td>SUBPARSER_BASE_RUNS_SUB</td>
<td>bidirectional</td>
</tr>
</tbody>
</table>
<p>Let’s see actual difference of behaviors.</p>
<p>The examples are taken from #1409 submitted by &#64;sgraham on github
Universal-ctags repository.</p>
<p><cite>input.cc</cite> and <cite>input.mojom</cite> are input files, and have the same
contents:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span> <span class="n">ABC</span><span class="p">();</span>
<span class="nb">int</span> <span class="n">main</span><span class="p">(</span><span class="n">void</span><span class="p">)</span>
<span class="p">{</span>
<span class="p">}</span>
</pre></div>
</div>
<p>C++ parser can capture <cite>main</cite> as a function. Mojom subparser defined in the
later runs on C++ parser and is for capturing <cite>ABC</cite>.</p>
<div class="section" id="shared-combination">
<h5>shared combination<a class="headerlink" href="#shared-combination" title="Permalink to this headline">¶</a></h5>
<p><cite>{shared}</cite> is specified, for <cite>input.cc</cite>, both tags capture by C++ parser
and mojom parser are recorded to tags file. For <cite>input.mojom</cite>, only
tags captured by mojom parser are recorded to tags file.</p>
<p>mojom-shared.ctags:</p>
<div class="highlight-ctags"><div class="highlight"><pre><span></span>--langdef=mojom{base=C++}{shared}
--map-mojom=+.mojom
--kinddef-mojom=f,function,functions
--regex-mojom=/^[ ]+([a-zA-Z]+)\(/\1/f/
</pre></div>
</div>
<p>tags for <cite>input.cc</cite>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>ABC input.cc        /^ ABC();$/;&quot;   f       language:mojom
main        input.cc        /^int main(void)$/;&quot;    f       language:C++    typeref:typename:int
</pre></div>
</div>
<p>tags for <cite>input.mojom</cite>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>ABC   input.mojom     /^ ABC();$/;&quot;   f       language:mojom
</pre></div>
</div>
<p>Mojom parser uses C++ parser internally but tags captured by C++ parser are
dropped in the output.</p>
<p><cite>{shared}</cite> is the default behavior. If none of <cite>{shared}</cite>, <cite>{dedicated}</cite>, nor
<cite>{bidirectional}</cite> is specified, it implies <cite>{shared}</cite>.</p>
</div>
<div class="section" id="dedicated-combination">
<h5>dedicated combination<a class="headerlink" href="#dedicated-combination" title="Permalink to this headline">¶</a></h5>
<p><cite>{dedicated}</cite> is specified, for <cite>input.cc</cite>, only tags capture by C++
parser are recorded to tags file. For <cite>input.mojom</cite>, both tags capture
by C++ parser and mojom parser are recorded to tags file.</p>
<p>mojom-dedicated.ctags:</p>
<div class="highlight-ctags"><div class="highlight"><pre><span></span>--langdef=mojom{base=C++}{dedicated}
--map-mojom=+.mojom
--kinddef-mojom=f,function,functions
--regex-mojom=/^[ ]+([a-zA-Z]+)\(/\1/f/
</pre></div>
</div>
<p>tags for <cite>input.cc</cite>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>main        input.cc        /^int main(void)$/;&quot;    f       language:C++    typeref:typename:int
</pre></div>
</div>
<p>tags for <cite>input.mojom</cite>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>ABC input.mojom     /^ ABC();$/;&quot;   f       language:mojom
main        input.mojom     /^int main(void)$/;&quot;    f       language:C++    typeref:typename:int
</pre></div>
</div>
<p>Mojom parser works only when <cite>.mojom</cite> file is given as input.</p>
</div>
<div class="section" id="bidirectional-combination">
<h5>bidirectional combination<a class="headerlink" href="#bidirectional-combination" title="Permalink to this headline">¶</a></h5>
<p><cite>{bidirectional}</cite> is specified, both tags capture by C++ parser and
mojom parser are recorded to tags file for either input <cite>input.cc</cite> and
<cite>input.mojom</cite>.</p>
<p>mojom-bidirectional.ctags:</p>
<div class="highlight-ctags"><div class="highlight"><pre><span></span>--langdef=mojom{base=C++}{bidirectional}
--map-mojom=+.mojom
--kinddef-mojom=f,function,functions
--regex-mojom=/^[ ]+([a-zA-Z]+)\(/\1/f/
</pre></div>
</div>
<p>tags for <cite>input.cc</cite>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>ABC input.cc        /^ ABC();$/;&quot;   f       language:mojom
main        input.cc        /^int main(void)$/;&quot;    f       language:C++    typeref:typename:int
</pre></div>
</div>
<p>tags for <cite>input.mojom</cite>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>ABC input.cc        /^ ABC();$/;&quot;   f       language:mojom
main        input.cc        /^int main(void)$/;&quot;    f       language:C++    typeref:typename:int
</pre></div>
</div>
</div>
</div>
<div class="section" id="listing-subparsers">
<h4><a class="toc-backref" href="#id30">Listing subparsers</a><a class="headerlink" href="#listing-subparsers" title="Permalink to this headline">¶</a></h4>
<p>Subparsers can be listed with <code class="docutils literal"><span class="pre">--list-subparser</span></code>:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --options<span class="o">=</span>NONE --options<span class="o">=</span>./linux.ctags --list-subparsers<span class="o">=</span>C
<span class="go">ctags: Notice: No options will be read from files or environment</span>
<span class="gp">#</span>NAME                          BASEPARSER           DIRECTION
<span class="go">linux                          C                    base =&gt; sub {shared}</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="changes-to-the-tags-file-format">
<h2><a class="toc-backref" href="#id31">Changes to the tags file format</a><a class="headerlink" href="#changes-to-the-tags-file-format" title="Permalink to this headline">¶</a></h2>
<div class="section" id="truncating-the-pattern-for-long-input-lines">
<h3><a class="toc-backref" href="#id32">Truncating the pattern for long input lines</a><a class="headerlink" href="#truncating-the-pattern-for-long-input-lines" title="Permalink to this headline">¶</a></h3>
<p>To prevent generating overly large tags files, a pattern field is
truncated, by default, when its size exceeds 96 bytes. A different
limit can be specified with <code class="docutils literal"><span class="pre">--pattern-length-limit=N</span></code>.</p>
<p>An input source file with long lines and multiple tag matches per
line can generate an excessively large tags file with an
unconstrained pattern length. For example, running ctags on a
minified JavaScript source file often exhibits this behaviour.</p>
</div>
</div>
<div class="section" id="reference-tags">
<h2><a class="toc-backref" href="#id33">Reference tags</a><a class="headerlink" href="#reference-tags" title="Permalink to this headline">¶</a></h2>
<p>Traditionally ctags collects the information for locating where a
language object is DEFINED.</p>
<p>In addition Universal-ctags supports reference tags. If the extra-tag
<code class="docutils literal"><span class="pre">r</span></code> is enabled, Universal-ctags also collects the information for
locating where a language object is REFERENCED. This feature was
proposed by &#64;shigio in #569 for GNU GLOBAL.</p>
<p>Here are some examples. Here is the target input file named reftag.c.</p>
<div class="highlight-c"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">&lt;stdio.h&gt;</span><span class="cp"></span>
<span class="cp">#include</span> <span class="cpf">&quot;foo.h&quot;</span><span class="cp"></span>
<span class="cp">#define TYPE point</span>
<span class="k">struct</span> <span class="n">TYPE</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">;</span> <span class="p">};</span>
<span class="n">TYPE</span> <span class="n">p</span><span class="p">;</span>
<span class="cp">#undef TYPE</span>
</pre></div>
</div>
<p>Traditional output:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags -o - reftag.c
<span class="go">TYPE        reftag.c        /^#define TYPE /;&quot;      d       file:</span>
<span class="go">TYPE        reftag.c        /^struct TYPE { int x, y; };$/;&quot;        s       file:</span>
<span class="go">p   reftag.c        /^TYPE p;$/;&quot;   v       typeref:typename:TYPE</span>
<span class="go">x   reftag.c        /^struct TYPE { int x, y; };$/;&quot;        m       struct:TYPE     typeref:typename:int    file:</span>
<span class="go">y   reftag.c        /^struct TYPE { int x, y; };$/;&quot;        m       struct:TYPE     typeref:typename:int    file:</span>
</pre></div>
</div>
<p>Output with the extra-tag <code class="docutils literal"><span class="pre">r</span></code> enabled:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-extras <span class="p">|</span> grep ^r
<span class="go">r   Include reference tags  off</span>
<span class="gp">$</span> ./ctags -o - --extras<span class="o">=</span>+r reftag.c
<span class="go">TYPE        reftag.c        /^#define TYPE /;&quot;      d       file:</span>
<span class="go">TYPE        reftag.c        /^#undef TYPE$/;&quot;       d       file:</span>
<span class="go">TYPE        reftag.c        /^struct TYPE { int x, y; };$/;&quot;        s       file:</span>
<span class="go">foo.h       reftag.c        /^#include &quot;foo.h&quot;/;&quot;   h</span>
<span class="go">p   reftag.c        /^TYPE p;$/;&quot;   v       typeref:typename:TYPE</span>
<span class="go">stdio.h     reftag.c        /^#include &lt;stdio.h&gt;/;&quot; h</span>
<span class="go">x   reftag.c        /^struct TYPE { int x, y; };$/;&quot;        m       struct:TYPE     typeref:typename:int    file:</span>
<span class="go">y   reftag.c        /^struct TYPE { int x, y; };$/;&quot;        m       struct:TYPE     typeref:typename:int    file:</span>
</pre></div>
</div>
<p><cite>#undef X</cite> and two <cite>#include</cite> are newly collected.</p>
<p>A reference tag may have “role” information representing how it is
referenced.  Universal-ctags prints the role information when the <cite>r</cite>
field is enabled with <code class="docutils literal"><span class="pre">--fields=+r</span></code>. If a tag doesn’t have a
specialized role, <cite>generic</cite> is used as the name of role.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span>  ./ctags -o - --extras<span class="o">=</span>+r --fields<span class="o">=</span>+r reftag.c
<span class="go">TYPE        reftag.c        /^#define TYPE /;&quot;      d       file:</span>
<span class="go">TYPE        reftag.c        /^#undef TYPE$/;&quot;       d       file:   role:undef</span>
<span class="go">TYPE        reftag.c        /^struct TYPE { int x, y; };$/;&quot;        s       file:</span>
<span class="go">foo.h       reftag.c        /^#include &quot;foo.h&quot;/;&quot;   h       role:local</span>
<span class="go">p   reftag.c        /^TYPE p;$/;&quot;   v       typeref:typename:TYPE</span>
<span class="go">stdio.h     reftag.c        /^#include &lt;stdio.h&gt;/;&quot; h       role:system</span>
<span class="go">x   reftag.c        /^struct TYPE { int x, y; };$/;&quot;        m       struct:TYPE     typeref:typename:int    file:</span>
<span class="go">y   reftag.c        /^struct TYPE { int x, y; };$/;&quot;        m       struct:TYPE     typeref:typename:int    file:</span>
</pre></div>
</div>
<p>The <cite>Reference tag marker</cite> field, <code class="docutils literal"><span class="pre">R</span></code>, is a specialized GNU global
requirement; D is used for the traditional definition tags, and R is
used for the new reference tags. The field can be used only with
<code class="docutils literal"><span class="pre">--_xformat</span></code>.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags -x --_xformat<span class="o">=</span><span class="s2">&quot;%R %-16N %4n %-16F %C&quot;</span> --extras<span class="o">=</span>+r reftag.c
<span class="go">D TYPE                3 reftag.c         #define TYPE point</span>
<span class="go">D TYPE                4 reftag.c         struct TYPE { int x, y; };</span>
<span class="go">D p                   5 reftag.c         TYPE p;</span>
<span class="go">D x                   4 reftag.c         struct TYPE { int x, y; };</span>
<span class="go">D y                   4 reftag.c         struct TYPE { int x, y; };</span>
<span class="go">R TYPE                6 reftag.c         #undef TYPE</span>
<span class="go">R foo.h               2 reftag.c         #include &quot;foo.h&quot;</span>
<span class="go">R stdio.h             1 reftag.c         #include &lt;stdio.h&gt;</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="#xformat"><span class="std std-ref">Customizing xref output</span></a> for more details about
this option.</p>
<p>Although the facility for collecting reference tags is implemented,
only a few parsers currently utilize it. All available roles can be
listed with <code class="docutils literal"><span class="pre">--list-roles</span></code>:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-roles
<span class="gp">#</span>LANGUAGE      KIND<span class="o">(</span>L/N<span class="o">)</span>         NAME                ENABLED DESCRIPTION
<span class="go">SystemdUnit    u/unit            Requires            on      referred in Requires key</span>
<span class="go">SystemdUnit    u/unit            Wants               on      referred in Wants key</span>
<span class="go">SystemdUnit    u/unit            After               on      referred in After key</span>
<span class="go">SystemdUnit    u/unit            Before              on      referred in Before key</span>
<span class="go">SystemdUnit    u/unit            RequiredBy          on      referred in RequiredBy key</span>
<span class="go">SystemdUnit    u/unit            WantedBy            on      referred in WantedBy key</span>
<span class="go">Yaml           a/anchor          alias               on      alias</span>
<span class="go">DTD            e/element         attOwner            on      attributes owner</span>
<span class="go">Automake       c/condition       branched            on      used for branching</span>
<span class="go">Cobol          S/sourcefile      copied              on      copied in source file</span>
<span class="go">Maven2         g/groupId         dependency          on      dependency</span>
<span class="go">DTD            p/parameterEntity elementName         on      element names</span>
<span class="go">DTD            p/parameterEntity condition           on      conditions</span>
<span class="go">LdScript       s/symbol          entrypoint          on      entry points</span>
<span class="go">LdScript       i/inputSection    discarded           on      discarded when linking</span>
<span class="go">...</span>
</pre></div>
</div>
<p>The first column shows the name of the parser.
The second column shows the letter/name of the kind.
The third column shows the name of the role.
The fourth column shows whether the role is enabled or not.
The fifth column shows the description of the role.</p>
<p>Currently ctags doesn’t provide the way for disabling a
specified role.</p>
</div>
<div class="section" id="automatic-parser-selection">
<h2><a class="toc-backref" href="#id34">Automatic parser selection</a><a class="headerlink" href="#automatic-parser-selection" title="Permalink to this headline">¶</a></h2>
<p>See “Choosing a proper parser in ctags” section.</p>
<div class="section" id="incompatible-changes-to-file-name-pattern-and-extension-handling">
<h3><a class="toc-backref" href="#id35">Incompatible changes to file name pattern and extension handling</a><a class="headerlink" href="#incompatible-changes-to-file-name-pattern-and-extension-handling" title="Permalink to this headline">¶</a></h3>
<p>When guessing a proper parser for a given input file, Exuberant-ctags
tests file name patterns AFTER file extensions (e-order).
Universal-ctags does this differently; it tests file name patterns
BEFORE file extensions (u-order).</p>
<p>This incompatible change is introduced to deal with the following
situation: “build.xml” is an input file. The Ant parser declares it
handles a file name pattern “build.xml” and another parser, Foo,
declares it handles a file extension “xml”.</p>
<p>Which parser should be used for parsing the input? The user may want
to use the Ant parser because the pattern it declares is more
specific than the extension Foo declares. However, in e-order, the
other parser, Foo, is chosen.</p>
<p>So Universal-ctags uses the u-order even though it introduces an
incompatibility.</p>
</div>
</div>
<div class="section" id="pseudo-tags">
<h2><a class="toc-backref" href="#id36">Pseudo tags</a><a class="headerlink" href="#pseudo-tags" title="Permalink to this headline">¶</a></h2>
<p>Pseudo tags are used to add meta data to a tags file. Universal-ctags
will utilize pseudo tags aggressively.</p>
<p>Universal-ctags is not mature yet; there is a possibility that
incompatible changes will be introduced. As a result tools reading
a tags file may not work as expected.</p>
<p>To mitigate this issue pseudo tags are employed to make a tags file
more self-descriptive. We hope some of the incompatibilities can be
overcome in client tools by utilizing this approach.</p>
<p>Example output:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags -o - --extras<span class="o">=</span>p --pseudo-tags<span class="o">=</span><span class="s1">&#39;TAG_KIND_DESCRIPTION&#39;</span> foo.c
<span class="go">!_TAG_KIND_DESCRIPTION!C    L,label /goto label/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    c,class /classes/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    d,macro /macro definitions/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    e,enumerator    /enumerators (values inside an enumeration)/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    f,function      /function definitions/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    g,enum  /enumeration names/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    h,header        /included header files/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    l,local /local variables/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    m,member        /class, struct, and union members/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    n,namespace     /namespaces/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    p,prototype     /function prototypes/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    s,struct        /structure names/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    t,typedef       /typedefs/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    u,union /union names/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    v,variable      /variable definitions/</span>
<span class="go">!_TAG_KIND_DESCRIPTION!C    x,externvar     /external and forward variable declarations/</span>
<span class="go">foo foo.c   /^foo (int i, int j)$/;&quot;        f</span>
<span class="go">main        foo.c   /^main (void)$/;&quot;       f</span>
</pre></div>
</div>
<div class="section" id="tag-kind-description">
<h3><a class="toc-backref" href="#id37"><code class="docutils literal"><span class="pre">TAG_KIND_DESCRIPTION</span></code></a><a class="headerlink" href="#tag-kind-description" title="Permalink to this headline">¶</a></h3>
<p>This is a newly introduced pseudo tag. It is not emitted by default.
It is emitted only when <code class="docutils literal"><span class="pre">--pseudo-tags=+TAG_KIND_DESCRIPTION</span></code> is
given.</p>
<p>This is for describing kinds; their letter, name, and description are
enumerated in the tag.</p>
<p>ctags emits <code class="docutils literal"><span class="pre">TAG_KIND_DESCRIPTION</span></code> with following format:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser}   {letter},{name} /{description}/
</pre></div>
</div>
<p>A backslash and a slash in {description} is escaped with a backslash.</p>
</div>
<div class="section" id="tag-kind-separator">
<h3><a class="toc-backref" href="#id38"><code class="docutils literal"><span class="pre">TAG_KIND_SEPARATOR</span></code></a><a class="headerlink" href="#tag-kind-separator" title="Permalink to this headline">¶</a></h3>
<p>This is a newly introduced pseudo tag. It is not emitted by default.
It is emitted only when <code class="docutils literal"><span class="pre">--pseudo-tags=+TAG_KIND_SEPARATOR</span></code> is
given.</p>
<p>This is for describing separators placed between two kinds in a
language.</p>
<p>Tag entries including the separators are emitted when <code class="docutils literal"><span class="pre">--extras=+q</span></code>
is given; fully qualified tags contain the separators. The separators
are used in scope information, too.</p>
<p>ctags emits <code class="docutils literal"><span class="pre">TAG_KIND_SEPARATOR</span></code> with following format:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser}   {sep}   /{upper}{lower}/
</pre></div>
</div>
<p>or</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser}   {sep}   /{lower}/
</pre></div>
</div>
<p>Here {parser} is the name of language. e.g. PHP.
{lower} is the letter representing the kind of the lower item.
{upper} is the letter representing the kind of the upper item.
{sep} is the separator placed between the upper item and the lower
item.</p>
<p>The format without {upper} is for representing a root separator. The
root separator is used as prefix for an item which has no upper scope.</p>
<p><cite>*</cite> given as {upper} is a fallback wild card; if it is given, the
{sep} is used in combination with any upper item and the item
specified with {lower}.</p>
<p>Each backslash character used in {sep} is escaped with an extra
backslash character.</p>
<p>Example output:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags -o - --extras<span class="o">=</span>+p --pseudo-tags<span class="o">=</span>  --pseudo-tags<span class="o">=</span>+TAG_KIND_SEPARATOR input.php
<span class="go">!_TAG_KIND_SEPARATOR!PHP    ::      /*c/</span>
<span class="go">...</span>
<span class="go">!_TAG_KIND_SEPARATOR!PHP    \\      /c/</span>
<span class="go">...</span>
<span class="go">!_TAG_KIND_SEPARATOR!PHP    \\      /nc/</span>
<span class="go">...</span>
</pre></div>
</div>
<p>The first line means <cite>::</cite> is used when combining something with an
item of the class kind.</p>
<p>The second line means <cite>\</cite> is used when a class item is at the top
level; no upper item is specified.</p>
<p>The third line means <cite>\</cite> is used when for combining a namespace item
(upper) and a class item (lower).</p>
<p>Of course, ctags uses the more specific line when choosing a
separator; the third line has higher priority than the first.</p>
</div>
<div class="section" id="tag-output-mode">
<h3><a class="toc-backref" href="#id39"><code class="docutils literal"><span class="pre">TAG_OUTPUT_MODE</span></code></a><a class="headerlink" href="#tag-output-mode" title="Permalink to this headline">¶</a></h3>
<p>This pseudo tag represents output mode: u-ctags or e-ctags.</p>
<p>See also <a class="reference internal" href="format.html#compat-output"><span class="std std-ref">Compatible output and weakness</span></a>.</p>
</div>
</div>
<div class="section" id="parser-own-fields">
<span id="id1"></span><h2><a class="toc-backref" href="#id40">Parser own fields</a><a class="headerlink" href="#parser-own-fields" title="Permalink to this headline">¶</a></h2>
<p>A tag has a <cite>name</cite>, an <cite>input</cite> file name, and a <cite>pattern</cite> as basic
information. Some fields like <cite>language:</cite>, <cite>signature:</cite>, etc are
attached to the tag as optional information.</p>
<p>In Exuberant-ctags, fields are common to all languages.
Universal-ctags extends the concept of fields; a parser can define
its own field. This extension was proposed by &#64;pragmaware in #857.</p>
<p>For implementing the parser own fields, the options for listing and
enabling/disabling fields are also extended.</p>
<p>In the output of <code class="docutils literal"><span class="pre">--list-fields</span></code>, the owner of the field is printed
in the <cite>LANGUAGE</cite> column:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-fields
<span class="gp">#</span>LETTER NAME            ENABLED LANGUAGE         XFMT  DESCRIPTION
<span class="go">...</span>
<span class="go">-       end             off     C                TRUE   end lines of various constructs</span>
<span class="go">-       properties      off     C                TRUE   properties (static, inline, mutable,...)</span>
<span class="go">-       end             off     C++              TRUE   end lines of various constructs</span>
<span class="go">-       template        off     C++              TRUE   template parameters</span>
<span class="go">-       captures        off     C++              TRUE   lambda capture list</span>
<span class="go">-       properties      off     C++              TRUE   properties (static, virtual, inline, mutable,...)</span>
<span class="go">-       sectionMarker   off     reStructuredText TRUE   character used for declaring section</span>
<span class="go">-       version         off     Maven2           TRUE   version of artifact</span>
</pre></div>
</div>
<p>e.g. reStructuredText is the owner of the sectionMarker field and
both C and C++ own the end field.</p>
<p><code class="docutils literal"><span class="pre">--list-fields</span></code> takes one optional argument, <cite>LANGUAGE</cite>. If it is
given, <code class="docutils literal"><span class="pre">--list-fields</span></code> prints only the fields for that parser:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-fields<span class="o">=</span>Maven2
<span class="gp">#</span>LETTER NAME            ENABLED LANGUAGE        XFMT  DESCRIPTION
<span class="go">-       version         off     Maven2          TRUE  version of artifact</span>
</pre></div>
</div>
<p>A parser own field only has a long name, no letter. For
enabling/disabling such fields, the name must be passed to
<code class="docutils literal"><span class="pre">--fields-&lt;LANG&gt;</span></code>.</p>
<p>e.g. for enabling the <cite>sectionMarker</cite> field owned by the
<cite>reStructuredText</cite> parser, use the following command line:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --fields-reStructuredText<span class="o">=</span>+<span class="o">{</span>sectionMarker<span class="o">}</span> ...
</pre></div>
</div>
<p>The wild card notation can be used for enabling/disabling parser own
fields, too. The following example enables all fields owned by the
<cite>C++</cite> parser.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --fields-C++<span class="o">=</span><span class="s1">&#39;*&#39;</span> ...
</pre></div>
</div>
<p><cite>*</cite> can also be used for specifying languages.</p>
<p>The next example is for enabling <cite>end</cite> fields for all languages which
have such a field.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --fields-<span class="s1">&#39;*&#39;</span><span class="o">=</span>+<span class="s1">&#39;{end}&#39;</span> ...
<span class="go">...</span>
</pre></div>
</div>
<p>In this case, using wild card notation to specify the language, not
only fields owned by parsers but also common fields having the name
specified (<cite>end</cite> in this example) are enabled/disabled.</p>
<p>Using the wild card notation to specify the language is helpful to
avoid incompatibilities between versions of Universal-ctags itself
(SELF INCOMPATIBLY).</p>
<p>In Universal-ctags development, a parser developer may add a new
parser own field for a certain language.  Sometimes other developers
then recognize it is meaningful not only for the original language
but also other languages. In this case the field may be promoted to a
common field. Such a promotion will break the command line
compatibility for <code class="docutils literal"><span class="pre">--fields-&lt;LANG&gt;</span></code> usage. The wild card for
<cite>&lt;LANG&gt;</cite> will help in avoiding this unwanted effect of the promotion.</p>
<p>With respect to the tags file format, nothing is changed when
introducing parser own fields; <cite>&lt;fieldname&gt;</cite>:<cite>&lt;value&gt;</cite> is used as
before and the name of field owner is never prefixed. The <cite>language:</cite>
field of the tag identifies the owner.</p>
</div>
<div class="section" id="parser-own-extras">
<h2><a class="toc-backref" href="#id41">Parser own extras</a><a class="headerlink" href="#parser-own-extras" title="Permalink to this headline">¶</a></h2>
<p>As man page of Exuberant-ctags says, <code class="docutils literal"><span class="pre">--extras</span></code> option specifies
whether to include extra tag entries for certain kinds of information.
This option is available in Universal-ctags, too.</p>
<p>In Universal-ctags it is extended; a parser can define its own
extra flags. They can be controlled with <code class="docutils literal"><span class="pre">--extras-&lt;LANG&gt;=[+|-]{...}</span></code>.</p>
<p>See some examples:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-extras
<span class="gp">#</span>LETTER NAME                   ENABLED LANGUAGE         DESCRIPTION
<span class="go">F       fileScope              TRUE    NONE             Include tags ...</span>
<span class="go">f       inputFile              FALSE   NONE             Include an entry ...</span>
<span class="go">p       pseudo                 FALSE   NONE             Include pseudo tags</span>
<span class="go">q       qualified              FALSE   NONE             Include an extra ...</span>
<span class="go">r       reference              FALSE   NONE             Include reference tags</span>
<span class="go">g       guest                  FALSE   NONE             Include tags ...</span>
<span class="go">-       whitespaceSwapped      TRUE    Robot            Include tags swapping ...</span>
</pre></div>
</div>
<p>See the <cite>LANGUAGE</cite> column. NONE means the extra flags are language
independent (common). They can be enabled or disabled with <cite>–extras=</cite> as before.</p>
<p>Look at <cite>whitespaceSwapped</cite>. Its language is <cite>Robot</cite>. This flag is enabled
by default but can be disabled with <cite>–extras-Robot=-{whitespaceSwapped}</cite>.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cat input.robot
<span class="go">*** Keywords ***</span>
<span class="go">it&#39;s ok to be correct</span>
<span class="go">    Python_keyword_2</span>

<span class="gp">$</span> ./ctags -o - input.robot
<span class="go">it&#39;s ok to be correct       input.robot     /^it&#39;s ok to be correct$/;&quot;     k</span>
<span class="go">it&#39;s_ok_to_be_correct       input.robot     /^it&#39;s ok to be correct$/;&quot;     k</span>

<span class="gp">$</span> ./ctags -o - --extras-Robot<span class="o">=</span>-<span class="s1">&#39;{whitespaceSwapped}&#39;</span> input.robot
<span class="go">it&#39;s ok to be correct       input.robot     /^it&#39;s ok to be correct$/;&quot;     k</span>
</pre></div>
</div>
<p>When disabled the name <cite>it’s_ok_to_be_correct</cite> is not included in the
tags output.  In other words, the name <cite>it’s_ok_to_be_correct</cite> is
derived from the name <cite>it’s ok to be correct</cite> when the extra flag is
enabled.</p>
<div class="section" id="discussion">
<h3><a class="toc-backref" href="#id42">Discussion</a><a class="headerlink" href="#discussion" title="Permalink to this headline">¶</a></h3>
<p>(This subsection should move to somewhere for developers.)</p>
<p>The question is what are extra tag entries. As far as I know none has
answered explicitly. I have two ideas in Universal-ctags. I
write “ideas”, not “definitions” here because existing parsers don’t
follow the ideas. They are kept as is in variety reasons but the
ideas may be good guide for people who wants to write a new parser
or extend an exiting parser.</p>
<p>The first idea is that a tag entry whose name is appeared in the input
file as is, the entry is NOT an extra. (If you want to control the
inclusion of such entries, the classical <code class="docutils literal"><span class="pre">--kind-&lt;LANG&gt;=[+|-]...</span></code> is
what you want.)</p>
<p>Qualified tags, whose inclusion is controlled by <code class="docutils literal"><span class="pre">--extras=+q</span></code>, is
explained well with this idea.
Let’s see an example:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cat input.py
<span class="go">class Foo:</span>
<span class="go">    def func (self):</span>
<span class="go">        pass</span>

<span class="gp">$</span> ./ctags -o - --extras<span class="o">=</span>+q --fields<span class="o">=</span>+E input.py
<span class="go">Foo input.py        /^class Foo:$/;&quot;        c</span>
<span class="go">Foo.func    input.py        /^    def func (self):$/;&quot;      m       class:Foo       extra:qualified</span>
<span class="go">func        input.py        /^    def func (self):$/;&quot;      m       class:Foo</span>
</pre></div>
</div>
<p><cite>Foo</cite> and <cite>func</cite> are in <cite>input.py</cite>. So they are no extra tags.  In
other hand, <cite>Foo.func</cite> is not in <cite>input.py</cite> as is. The name is
generated by ctags as a qualified extra tag entry.
<cite>whitespaceSwapped</cite> extra flag of  <cite>Robot</cite> parser is also aligned well
on the idea.</p>
<p>I don’t say all parsers follows this idea.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cat input.cc
<span class="go">class A</span>
<span class="go">{</span>
<span class="go">  A operator+ (int);</span>
<span class="go">};</span>

<span class="gp">$</span> ./ctags --kinds-all<span class="o">=</span><span class="s1">&#39;*&#39;</span> --fields<span class="o">=</span> -o - input.cc
<span class="go">A   input.cc        /^class A$/</span>
<span class="go">operator +  input.cc        /^  A operator+ (int);$/</span>
</pre></div>
</div>
<p>In this example <cite>operator+</cite> is in <cite>input.cc</cite>.
In other hand, <cite>operator +</cite>  is in the ctags output as non extra tag entry.
See a whitespace between the keyword <cite>operator</cite> and <cite>+</cite> operator.
This is an exception of the first idea.</p>
<p>The second idea is that if the <em>inclusion</em> of a tag cannot be
controlled well with <code class="docutils literal"><span class="pre">--kind-&lt;LANG&gt;=[+|-]...</span></code>, the tag may be an
extra.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> cat input.c
<span class="go">static int foo (void)</span>
<span class="go">{</span>
<span class="go">        return 0;</span>
<span class="go">}</span>
<span class="go">int bar (void)</span>
<span class="go">{</span>
<span class="go">        return 1;</span>
<span class="go">}</span>

<span class="gp">$</span> ./ctags --sort<span class="o">=</span>no -o - --extras<span class="o">=</span>+F input.c
<span class="go">foo input.c /^static int foo (void)$/;&quot;     f       typeref:typename:int    file:</span>
<span class="go">bar input.c /^int bar (void)$/;&quot;    f       typeref:typename:int</span>

<span class="gp">$</span> ./ctags -o - --extras<span class="o">=</span>-F input.c
<span class="go">foo input.c /^static int foo (void)$/;&quot;     f       typeref:typename:int    file:</span>

<span class="gp">$</span>
</pre></div>
</div>
<p>Function <cite>foo</cite> of C language is included only when <cite>F</cite> extra flag
is enabled. Both <cite>foo</cite> and <cite>bar</cite> are functions. Their inclusions
can be controlled with <cite>f</cite> kind of C language: <code class="docutils literal"><span class="pre">--kind-C=[+|-]f</span></code>.</p>
<p>The difference between static modifier or implicit extern modifier in
a function definition is handled by <cite>F</cite> extra flag.</p>
<p>Basically the concept kind is for handling the kinds of language
objects: functions, variables, macros, types, etc. The concept extra
can handle the other aspects like scope (static or extern).</p>
<p>However, a parser developer can take another approach instead of
introducing parser own extra; one can prepare <cite>staticFunction</cite> and
<cite>exportedFunction</cite> as kinds of one’s parser.  The second idea is a
just guide; the parser developer must decide suitable approach for the
target language.</p>
<p>Anyway, in the second idea, <code class="docutils literal"><span class="pre">--extra</span></code> is for controlling inclusion
of tags. If what you want is not about inclusion, <code class="docutils literal"><span class="pre">--param-&lt;LANG&gt;</span></code>
can be used as the last resort.</p>
</div>
</div>
<div class="section" id="parser-own-parameter">
<h2><a class="toc-backref" href="#id43">Parser own parameter</a><a class="headerlink" href="#parser-own-parameter" title="Permalink to this headline">¶</a></h2>
<p>To control the detail of a parser, <code class="docutils literal"><span class="pre">--param-&lt;LANG&gt;</span></code> option is introduced.
<code class="docutils literal"><span class="pre">--kinds-&lt;LANG&gt;</span></code>, <code class="docutils literal"><span class="pre">--fields-&lt;LANG&gt;</span></code>, <code class="docutils literal"><span class="pre">--extras-&lt;LANG&gt;</span></code>
can be used for customizing the behavior of a parser specified with <code class="docutils literal"><span class="pre">&lt;LANG&gt;</span></code>.</p>
<p><code class="docutils literal"><span class="pre">--param-&lt;LANG&gt;</span></code> should be used for aspects of the parser that
the options(kinds, fields, extras) cannot handle well.</p>
<p>A parser defines a set of parameters. Each parameter has name and
takes an argument. A user can set a parameter with following notation</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">param</span><span class="o">-&lt;</span><span class="n">LANG</span><span class="o">&gt;</span><span class="p">:</span><span class="n">name</span><span class="o">=</span><span class="n">arg</span>
</pre></div>
</div>
<p>An example of specifying a parameter</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">param</span><span class="o">-</span><span class="n">CPreProcessor</span><span class="p">:</span><span class="n">if0</span><span class="o">=</span><span class="n">true</span>
</pre></div>
</div>
<p>Here <cite>if0</cite> is a name of parameter of CPreProcessor parser and
<cite>true</cite> is the value of it.</p>
<p>All available parameters can be listed with <code class="docutils literal"><span class="pre">--list-params</span></code> option.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --list-params
<span class="gp">#</span>PARSER         NAME     DESCRIPTION
<span class="go">CPreProcessor   if0      examine code within &quot;#if 0&quot; branch (true or [false])</span>
<span class="go">CPreProcessor   ignore   a token to be specially handled</span>
</pre></div>
</div>
<p>(At this time only CPreProcessor parser has parameters.)</p>
</div>
<div class="section" id="customizing-xref-output">
<span id="xformat"></span><h2><a class="toc-backref" href="#id44">Customizing xref output</a><a class="headerlink" href="#customizing-xref-output" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal"><span class="pre">--_xformat</span></code> option allows a user to customize the cross reference
(xref) output enabled with <code class="docutils literal"><span class="pre">-x</span></code>.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">_xformat</span><span class="o">=</span><span class="n">FORMAT</span>
</pre></div>
</div>
<p>The notation for FORMAT is similar to that employed by <cite>printf(3)</cite> in
the C language; <cite>%</cite> represents a slot which is substituted with a
field value when printing. You can specify multiple slots in FORMAT.
Here field means an item listed with <code class="docutils literal"><span class="pre">-list-fields</span></code> option.</p>
<p>The notation of a slot:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">%</span><span class="p">[</span><span class="n">WIDTH</span><span class="o">-</span><span class="n">AND</span><span class="o">-</span><span class="n">ADJUSTMENT</span><span class="p">]</span><span class="n">FIELD</span><span class="o">-</span><span class="n">SPECIFIER</span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">FIELD-SPECIFIER</span></code> specifies a field whose value is printed.
Short notation and long notation are available. They can be mixed
in a FORMAT. Specifying a field with either notation, one or more
fields are activated internally.</p>
<p>The short notation is just a letter listed in the LETTER column of
the <code class="docutils literal"><span class="pre">--list-fields</span></code> output.</p>
<p>The long notation is a name string surrounded by braces(<cite>{</cite> and
<cite>}</cite>). The name string is listed in the NAME column of the output of
the same option. To specify a field owned by a parser, prepend
the parser name to the name string with <cite>.</cite> as a separator.</p>
<p>Wild card (<cite>*</cite>) can be used where a parser name is specified. In this
case both common and parser own fields are activated and printed.
If a common field and a parser own field have the same name,
the common field has higher priority.</p>
<p><cite>WIDTH-AND-ADJUSTMENT</cite> is a positive or negative number.
The absolute value of the number is used as the width of
the column where a field is printed. The printing is
right adjusted when a positive value is given, and left
adjusted when negative.</p>
<p>An example of specifying common fields:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span>  ./ctags -x --_xformat<span class="o">=</span><span class="s2">&quot;%-20N %4n %-16{input}|&quot;</span> main/main.c <span class="p">|</span> head
<span class="go">CLOCKS_PER_SEC        360 main/main.c     |</span>
<span class="go">CLOCKS_PER_SEC        364 main/main.c     |</span>
<span class="go">CLOCK_AVAILABLE       358 main/main.c     |</span>
<span class="go">CLOCK_AVAILABLE       363 main/main.c     |</span>
<span class="go">Totals                 87 main/main.c     |</span>
<span class="go">__anonae81ef0f0108     87 main/main.c     |</span>
<span class="go">addTotals             100 main/main.c     |</span>
<span class="go">batchMakeTags         436 main/main.c     |</span>
<span class="go">bytes                  87 main/main.c     |</span>
<span class="go">clock                 365 main/main.c     |</span>
</pre></div>
</div>
<p>Here <cite>%-20N %4n %-16{input}|</cite> is a format string. Let’s look at the
elements of the format.</p>
<p><cite>%-20N</cite></p>
<blockquote>
<div>The short notation is used here.
The element means filling the slot with the name of the tag.
The width of the column is 20 characters and left adjusted.</div></blockquote>
<p><cite>%4n</cite></p>
<blockquote>
<div>The short notation is used here.
The element means filling the slot with the line number of
the tag. The width of the column is 4 characters and right
adjusted.</div></blockquote>
<p><cite>%-16{input}</cite></p>
<blockquote>
<div>The long notation is used here.
The element means filling the slot with the input file name
where the tag is defined. The width of column is 16
characters and left adjusted.</div></blockquote>
<p><cite>|</cite></p>
<blockquote>
<div>Printed as is.</div></blockquote>
<p>Another example of specifying parser own fields:</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span>  ./ctags -x --_xformat<span class="o">=</span><span class="s2">&quot;%-20N [%10{C.properties}]&quot;</span> main/main.c
<span class="go">CLOCKS_PER_SEC       [          ]</span>
<span class="go">CLOCK_AVAILABLE      [          ]</span>
<span class="go">Totals               [          ]</span>
<span class="go">__anonae81ef0f0108   [          ]</span>
<span class="go">addTotals            [    extern]</span>
<span class="go">batchMakeTags        [    static]</span>
<span class="go">bytes                [          ]</span>
<span class="go">clock                [          ]</span>
<span class="go">clock                [    static]</span>
<span class="go">...</span>
</pre></div>
</div>
<p>Here <cite>“%-20N [%10{C.properties}]”</cite> is a format string. Let’s look at
the elements of the format.</p>
<p><cite>%-20N</cite></p>
<blockquote>
<div>Already explained in the first example.</div></blockquote>
<p><cite>[</cite> and <cite>]</cite></p>
<blockquote>
<div>Printed as is.</div></blockquote>
<p><cite>%10{C.properties}</cite></p>
<blockquote>
<div>The long notation is used here.
The element means filling the slot with the value
of the properties field of the C parser.
The width of the column is 10 characters and right adjusted.</div></blockquote>
</div>
<div class="section" id="incompatible-changes-in-command-line">
<h2><a class="toc-backref" href="#id45">Incompatible changes in command line</a><a class="headerlink" href="#incompatible-changes-in-command-line" title="Permalink to this headline">¶</a></h2>
<div class="section" id="d-option">
<h3><a class="toc-backref" href="#id46"><code class="docutils literal"><span class="pre">-D</span></code> option</a><a class="headerlink" href="#d-option" title="Permalink to this headline">¶</a></h3>
<p>For a ctags binary that had debugging output enabled in the build config
stage, <code class="docutils literal"><span class="pre">-D</span></code> was used for specifying the level of debugging
output. It is changed to <code class="docutils literal"><span class="pre">-d</span></code>. This change is not critical because
<code class="docutils literal"><span class="pre">-D</span></code> option was not described in ctags.1 man page.</p>
<p>Instead <code class="docutils literal"><span class="pre">-D</span></code> is used for defining a macro in CPreProcessor parser.</p>
</div>
</div>
<div class="section" id="skipping-utf-8-bom">
<h2><a class="toc-backref" href="#id47">Skipping utf-8 BOM</a><a class="headerlink" href="#skipping-utf-8-bom" title="Permalink to this headline">¶</a></h2>
<p>The three bytes sequence(‘xEFxBBxBF’) at the head of an input
file is skipped when parsing.</p>
<p>TODO:</p>
<ul class="simple">
<li>Do the same in guessing and selecting parser stage.</li>
<li>Refect the BOM detection to encoding option</li>
</ul>
</div>
<div class="section" id="readtags">
<h2><a class="toc-backref" href="#id48">Readtags</a><a class="headerlink" href="#readtags" title="Permalink to this headline">¶</a></h2>
<div class="section" id="printing-line-numbers-with-n">
<h3><a class="toc-backref" href="#id49">Printing line numbers with <code class="docutils literal"><span class="pre">-n</span></code></a><a class="headerlink" href="#printing-line-numbers-with-n" title="Permalink to this headline">¶</a></h3>
<p>If both <code class="docutils literal"><span class="pre">-e</span></code> and <code class="docutils literal"><span class="pre">-n</span></code> are given, readtags prints the <cite>line:</cite>
field.</p>
</div>
<div class="section" id="filtering-in-readtags-command">
<h3><a class="toc-backref" href="#id50">Filtering in readtags command</a><a class="headerlink" href="#filtering-in-readtags-command" title="Permalink to this headline">¶</a></h3>
<p>readtags has ability to find tag entries by name.</p>
<p>The concept of filtering is inspired by the display filter of
Wireshark. You can specify more complex conditions for searching.
Currently this feature is available only on platforms where
<cite>fmemopen</cite> is available as part of libc. Filtering in readtags is an
experimental feature.</p>
<p>The syntax of filtering rules is based on the Scheme language, a
variant of Lisp. The language has prefix notation and parentheses.</p>
<p>Before printing an entry from the tags file, readtags evaluates an
expression (S expression or sexp) given as an option argument to
<code class="docutils literal"><span class="pre">-Q</span></code>. As the result of the evaluation, readtags gets a value. false
represented as <cite>#f</cite>, indicates rejection: readtags doesn’t print it.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>SEXP =
     LIST
     INTEGER
     BOOLEAN
     STRING
     SYMBOL

     LIST = ( SEXP... ) | ()
     INTEGER = [0-9]+
     BOOLEAN = #t | #f
     STRING  = &quot;...&quot;
     SYMBOL  = null?
                 and
                  or
                 not
                 eq?
                   &lt;
                   &gt;
                  &lt;=
                  &gt;=
             prefix?
             suffix?
             substr?
              member
                   $
               $name
              $input
             $access
               $file
           $language
     $implementation
               $line
               $kind
               $role
            $pattern
           $inherits
         $scope-kind
         $scope-name
                $end
</pre></div>
</div>
<p>All symbols starting with <cite>$</cite> represent a field of a tag entry which
is being tested against the S expression. Most will evaluate as a
string or <cite>#f</cite>. It evaluates to <cite>#f</cite> when the field doesn’t exist.
<cite>$inherits</cite> is evaluated to a list of strings if the entry has an
<cite>inherits</cite> field. The <cite>scope</cite> field holds structured data: the kind
and name of the upper scope combined with <cite>:</cite>. The kind part is
mapped to <cite>$scope-kind</cite>, and the name part to <cite>$scope-name</cite>.</p>
<p><cite>$scope-kind</cite> and <cite>$scope-name</cite> can only be used if the input tags
file is generated by ctags with <code class="docutils literal"><span class="pre">--fields=+Z</span></code>.</p>
<p>All symbols not prefixed with <cite>$</cite> are operators. When using these,
put them at the head(car) of list. The rest(cdr) of the list is
passed to the operator as arguments. Many of them are also available
in the Scheme language; see the other documents.</p>
<p>prefix?, suffix?, and substr? may only be available in this
implementation. All of them take two strings. The first one
is called the target.</p>
<p>The exception in the above naming convention is the <cite>$</cite> operator.
<cite>$</cite> is a generic accessor for accessing extension fields.
<cite>$</cite> takes one argument: the name of an extension field.
It returns the value of the field as a string if a value
is given, or <cite>#f</cite>.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>(prefix? &quot;TARGET&quot; &quot;TA&quot;)
=&gt; #t

(prefix? &quot;TARGET&quot; &quot;RGET&quot;)
=&gt; #f

(prefix? &quot;TARGET&quot; &quot;RGE&quot;)
=&gt; #f

(suffix? &quot;TARGET&quot; &quot;TA&quot;)
=&gt; #f

(suffix? &quot;TARGET&quot; &quot;RGET&quot;)
=&gt; #t

(suffix? &quot;TARGET&quot; &quot;RGE&quot;)
=&gt; #f

(substr? &quot;TARGET&quot; &quot;TA&quot;)
=&gt; #t

(suffix? &quot;TARGET&quot; &quot;RGET&quot;)
=&gt; #t

(suffix? &quot;TARGET&quot; &quot;RGE&quot;)
=&gt; #t

(and (suffix? &quot;TARGET&quot; &quot;TARGET&quot;)
     (prefix? &quot;TARGET&quot; &quot;TARGET&quot;)
     (substr? &quot;TARGET&quot; &quot;TARGET&quot;)
=&gt; #t
</pre></div>
</div>
<p>Let’s see examples.</p>
</div>
<div class="section" id="examples-of-input">
<h3><a class="toc-backref" href="#id51">Examples of input</a><a class="headerlink" href="#examples-of-input" title="Permalink to this headline">¶</a></h3>
<p>Create the tags file (<em>foo.tags</em>) with following command line</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./ctags --fields<span class="o">=</span><span class="s1">&#39;*&#39;</span> --extras<span class="o">=</span><span class="s1">&#39;*&#39;</span> -o foo.tags foo.py
</pre></div>
</div>
<p>for following input (<em>foo.py</em>)</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">aq</span> <span class="p">():</span>
        <span class="k">pass</span>
    <span class="k">def</span> <span class="nf">aw</span> <span class="p">():</span>
        <span class="k">pass</span>
    <span class="k">def</span> <span class="nf">ae</span> <span class="p">():</span>
        <span class="k">pass</span>
    <span class="k">class</span> <span class="nc">A</span><span class="p">:</span>
        <span class="k">pass</span>
<span class="k">class</span> <span class="nc">Bar</span> <span class="p">(</span><span class="n">Foo</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">bq</span> <span class="p">():</span>
        <span class="k">pass</span>
    <span class="k">def</span> <span class="nf">bw</span> <span class="p">():</span>
        <span class="k">pass</span>
    <span class="k">class</span> <span class="nc">B</span><span class="p">:</span>
        <span class="k">pass</span>

<span class="k">class</span> <span class="nc">Baz</span> <span class="p">(</span><span class="n">Foo</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">bq</span> <span class="p">():</span>
        <span class="k">pass</span>
    <span class="k">def</span> <span class="nf">bw</span> <span class="p">():</span>
        <span class="k">pass</span>
    <span class="k">class</span> <span class="nc">C</span><span class="p">:</span>
        <span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="examples-of-filter-expressions">
<h3><a class="toc-backref" href="#id52">Examples of filter expressions</a><a class="headerlink" href="#examples-of-filter-expressions" title="Permalink to this headline">¶</a></h3>
<ul>
<li><p class="first">Print entries ending with “q”</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./readtags -e -t foo.tags -Q <span class="s1">&#39;(suffix? $name &quot;q&quot;)&#39;</span> -l
<span class="go">Bar.bq  foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Bar access:public   signature:()</span>
<span class="go">Baz.bq  foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
<span class="go">Foo.aq  foo.py  /^    def aq ():$/;&quot;    kind:member     language:Python scope:class:Foo access:public   signature:()</span>
<span class="go">aq      foo.py  /^    def aq ():$/;&quot;    kind:member     language:Python scope:class:Foo access:public   signature:()</span>
<span class="go">bq      foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Bar access:public   signature:()</span>
<span class="go">bq      foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
</pre></div>
</div>
</li>
<li><p class="first">Print members of Baz</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./readtags -e -t foo.tags -Q <span class="s1">&#39;(and (eq? $kind &quot;member&quot;) (eq? &quot;Baz&quot; $scope-name))&#39;</span> -l
<span class="go">Baz.bq  foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
<span class="go">Baz.bw  foo.py  /^    def bw ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
<span class="go">bq      foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
<span class="go">bw      foo.py  /^    def bw ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
</pre></div>
</div>
</li>
<li><p class="first">Print only fully qualified entries (assuming “.” is used as the separator)</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./readtags -e -t foo.tags -Q <span class="s1">&#39;(and (eq? $kind &quot;member&quot;) (substr? $name &quot;.&quot;))&#39;</span> -l
<span class="go">Bar.bq  foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Bar access:public   signature:()</span>
<span class="go">Bar.bw  foo.py  /^    def bw ():$/;&quot;    kind:member     language:Python scope:class:Bar access:public   signature:()</span>
<span class="go">Baz.bq  foo.py  /^    def bq ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
<span class="go">Baz.bw  foo.py  /^    def bw ():$/;&quot;    kind:member     language:Python scope:class:Baz access:public   signature:()</span>
<span class="go">Foo.ae  foo.py  /^    def ae ():$/;&quot;    kind:member     language:Python scope:class:Foo access:public   signature:()</span>
<span class="go">Foo.aq  foo.py  /^    def aq ():$/;&quot;    kind:member     language:Python scope:class:Foo access:public   signature:()</span>
<span class="go">Foo.aw  foo.py  /^    def aw ():$/;&quot;    kind:member     language:Python scope:class:Foo access:public   signature:()</span>
</pre></div>
</div>
</li>
<li><p class="first">Print only classes inheriting Foo</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> ./readtags  -e -t foo.tags -Q <span class="s1">&#39;(and (member &quot;Foo&quot; $inherits) (eq? $kind &quot;class&quot;))&#39;</span> -l
<span class="go">Bar     foo.py  /^class Bar (Foo):$/;&quot;  kind:class      language:Python inherits:Foo    access:public</span>
<span class="go">Baz     foo.py  /^class Baz (Foo): $/;&quot; kind:class      language:Python inherits:Foo    access:public</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Introduced changes</a><ul>
<li><a class="reference internal" href="#importing-changes-from-exuberant-ctags">Importing changes from Exuberant-ctags</a></li>
<li><a class="reference internal" href="#parser-related-changes">Parser related changes</a><ul>
<li><a class="reference internal" href="#fully-rewritten-parsers">Fully rewritten parsers</a></li>
<li><a class="reference internal" href="#new-parsers">New parsers</a></li>
<li><a class="reference internal" href="#heavily-improved-parsers">Heavily improved parsers</a></li>
<li><a class="reference internal" href="#f-kind-usage"><cite>F</cite> kind usage</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-and-extended-options">New and extended options</a><ul>
<li><a class="reference internal" href="#wildcard-in-options">Wildcard in options</a></li>
<li><a class="reference internal" href="#long-names-in-kinds-fields-and-extra-options">Long names in kinds, fields, and extra options</a></li>
<li><a class="reference internal" href="#notice-messages-and-quiet">Notice messages and <code class="docutils literal"><span class="pre">--quiet</span></code></a></li>
<li><a class="reference internal" href="#input-encoding-encoding-and-output-encoding-encoding"><code class="docutils literal"><span class="pre">--input-encoding=ENCODING</span></code> and <code class="docutils literal"><span class="pre">--output-encoding=ENCODING</span></code></a></li>
<li><a class="reference internal" href="#extra-tag-entries-extras">Extra tag entries (<code class="docutils literal"><span class="pre">--extras</span></code>)</a></li>
<li><a class="reference internal" href="#options-for-inspecting-ctags-internals">Options for inspecting ctags internals</a></li>
<li><a class="reference internal" href="#kinds-synchronization">Kinds synchronization</a></li>
<li><a class="reference internal" href="#put-field-prefix-options"><code class="docutils literal"><span class="pre">--put-field-prefix</span></code> options</a></li>
<li><a class="reference internal" href="#maxdepth-option"><code class="docutils literal"><span class="pre">--maxdepth</span></code> option</a></li>
<li><a class="reference internal" href="#map-lang-option"><code class="docutils literal"><span class="pre">--map-&lt;LANG&gt;</span></code> option</a></li>
<li><a class="reference internal" href="#guessing-parser-from-file-contents-g-option">Guessing parser from file contents (<code class="docutils literal"><span class="pre">-G</span></code> option)</a></li>
<li><a class="reference internal" href="#enabling-disabling-pseudo-tags-pseudo-tags-option">Enabling/disabling pseudo tags (<code class="docutils literal"><span class="pre">--pseudo-tags</span></code> option)</a></li>
<li><a class="reference internal" href="#json-output">JSON output</a></li>
<li><a class="reference internal" href="#always-and-never-as-an-argument-for-tag-relative">“always” and “never” as an argument for –tag-relative</a></li>
<li><a class="reference internal" href="#defining-a-macro-in-cpreprocessor-input">Defining a macro in CPreProcessor input</a></li>
<li><a class="reference internal" href="#interactive-mode"><code class="docutils literal"><span class="pre">--_interactive</span></code> Mode</a></li>
<li><a class="reference internal" href="#defining-a-kind">Defining a kind</a></li>
<li><a class="reference internal" href="#defining-an-extra">Defining an extra</a></li>
<li><a class="reference internal" href="#defining-a-subparser">Defining a subparser</a><ul>
<li><a class="reference internal" href="#basic">Basic</a></li>
<li><a class="reference internal" href="#directions">Directions</a><ul>
<li><a class="reference internal" href="#shared-combination">shared combination</a></li>
<li><a class="reference internal" href="#dedicated-combination">dedicated combination</a></li>
<li><a class="reference internal" href="#bidirectional-combination">bidirectional combination</a></li>
</ul>
</li>
<li><a class="reference internal" href="#listing-subparsers">Listing subparsers</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#changes-to-the-tags-file-format">Changes to the tags file format</a><ul>
<li><a class="reference internal" href="#truncating-the-pattern-for-long-input-lines">Truncating the pattern for long input lines</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reference-tags">Reference tags</a></li>
<li><a class="reference internal" href="#automatic-parser-selection">Automatic parser selection</a><ul>
<li><a class="reference internal" href="#incompatible-changes-to-file-name-pattern-and-extension-handling">Incompatible changes to file name pattern and extension handling</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pseudo-tags">Pseudo tags</a><ul>
<li><a class="reference internal" href="#tag-kind-description"><code class="docutils literal"><span class="pre">TAG_KIND_DESCRIPTION</span></code></a></li>
<li><a class="reference internal" href="#tag-kind-separator"><code class="docutils literal"><span class="pre">TAG_KIND_SEPARATOR</span></code></a></li>
<li><a class="reference internal" href="#tag-output-mode"><code class="docutils literal"><span class="pre">TAG_OUTPUT_MODE</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#parser-own-fields">Parser own fields</a></li>
<li><a class="reference internal" href="#parser-own-extras">Parser own extras</a><ul>
<li><a class="reference internal" href="#discussion">Discussion</a></li>
</ul>
</li>
<li><a class="reference internal" href="#parser-own-parameter">Parser own parameter</a></li>
<li><a class="reference internal" href="#customizing-xref-output">Customizing xref output</a></li>
<li><a class="reference internal" href="#incompatible-changes-in-command-line">Incompatible changes in command line</a><ul>
<li><a class="reference internal" href="#d-option"><code class="docutils literal"><span class="pre">-D</span></code> option</a></li>
</ul>
</li>
<li><a class="reference internal" href="#skipping-utf-8-bom">Skipping utf-8 BOM</a></li>
<li><a class="reference internal" href="#readtags">Readtags</a><ul>
<li><a class="reference internal" href="#printing-line-numbers-with-n">Printing line numbers with <code class="docutils literal"><span class="pre">-n</span></code></a></li>
<li><a class="reference internal" href="#filtering-in-readtags-command">Filtering in readtags command</a></li>
<li><a class="reference internal" href="#examples-of-input">Examples of input</a></li>
<li><a class="reference internal" href="#examples-of-filter-expressions">Examples of filter expressions</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="index.html"
                        title="previous chapter">Universal-ctags Hacking Guide</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="reporting.html"
                        title="next chapter">Request for extenting a parser (or Reporting a bug of parser)</a></p>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="reporting.html" title="Request for extenting a parser (or Reporting a bug of parser)"
             >next</a> |</li>
        <li class="right" >
          <a href="index.html" title="Universal-ctags Hacking Guide"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2015, Universal Ctags Team.
      Last updated on 19 Dec 2017.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.4.
    </div>
  </body>
</html>